Creating a wallet using Agent API

The Agent API is a REST API that allows external services to act as agents in TAG Neuron® networks, and manage legal identities, wallets, smart contracts, Neuro-Feature tokens, etc., for their users. This article describes how this API can be used to allow such external services to create wallets. The flow is as follows:

• First you select a Neuron®
• Once a Neuron® is selected, you create an account on the Neuron®.
• You then create at least one cryptographic key, that you will use for signatures.
• You apply for a legal identity on the account, using the cryptographic key and meta-data about the person (natural or legal) that will receive the wallet.
• Once the application has been reviewed and approved, the wallet is automatically created and can be used.

Selecting Neuron

The Neuron® network is a federated network where independent Neurons operating on their own domains interoperate to create a globally scalable network. The first step is selecting which Neuron® to connect to. You have different options:

• You can use a predefined Neuron®. In this case, you would typically receive the domain name of the Neuron® directly from the operator. You might also receive an API key and secret (see below) associated with that Neuron®.

• You can use the TAG onboading process to select a Neuron®, depending on the client’s location and purpose for connecting. The process is documented in a separate repository (see previous link). The onboarding process validates the end-user’s e-mail address and phone number, and returns the domain name, and associated API key and secret, for creating an account on that Neuron®.

• You can use a custom onboarding process, where a provider has customized access to their own set of featured Neurons. Apart from the domain name used to initiate the onboarding process, the process is otherwise similar to the TAG onboarding process.

• You can scan an onboarding QR code, to receive the relevant onboarding information. Three variants of onboarding codes exist: One that allows you to create an account on a Neuron®, one that already contains access to an existing account, and one that corresponds to a transfer of an account, including legal identity and wallet. (See link for more information.)

Note: You can call the DomainInfo resource of the Agent API, to get localized information about the selected domain.

Note 2: Your operator might already have given you an account for use with the Agent API. In that case, proceed with Sessions and Login, below.

Creating Account

Once a Neuron® has been selected, you have two options for creating an account on the Neuron®:

• You can use the Create API resource to create an account. This method requires, apart from the domain name, username, password and associated e-mail address, also a corresponding API Key and secret. A nonce value is also required, to assure all signatures are unique. Make sure the nonce value is unique for every call.

  If you create an account using this resource, you will automatically get a session token (which is a JWT token that is used as a Bearer token in subsequent calls to Agent API).

• Optionally, the operator of the Neuron® can also choose to enable the CreateWebForm resource, that allows you to embed the account creation properties in a web form displayed to the user. This resource does not require an API Key and secret for the integration. Instead, the operators configures the Neuron® with an API key and secret for use with this resource, on the Neuron® itself. Instead, access to the resource is protected using reCAPTCHA.

  When creating an account using this resource, you do not get a session token automatically. Instead, you have to call the GetSessionToken afterwards, to get a session token for the newly created account.

Verifying e-Mail address

If the the Create or CreateWebForm resources return a successful result, an account is created, albeit in a suspended or disabled state. This protects the account name from being taken by other users for a while, but the account cannot yet be used, i.e you cannot login to the account. To enable the account, you need to verify the e-mail address provided in the account creation call. Part of the creation call is to send out a verification e-mail to the address provided. This e-mail contains a code. You verify the e-mail address by calling the VerifyEMail resource with the code provided in the e-mail.

Note: Calling the Create and verify e-mails too many times without successfully verifying the e-mail addresses provided will result in a temporary block at first, and a permanent block if errors persist.

Sessions and Login

Immediately after creating an account, you are given a session token that helps you maintain a session with the Agent API. You select the duration of this session token in the original call, but it cannot exceed 3600 s (i.e. 1 h). Before the token expires, you need to call the Refresh resource if you want to maintain the session, to get a new token for the session. If you use an API implementation, such token maintanence is probably implemented “under the hood”, meaning you do not have to worry about this refresh. If you implement the API yourself, you will have to make sure token refreshing is implemented as well. If you know you will no longer need the session, you can call the Logout resource, to obsolete the current token.

If you want to login again, and create a new session, you have two options:

• You can use the Login resource, that allows you to login if you have the credentials, using a relatively high level of security, even if underlying HTTP libraries lack strong authentication algorithms. (This option is the recommended resource to use.)

• There is also a WwwLogin resource available, for authentication using the WWW-Authenticate header. This resource requires Neuron® and clients agree on choice of (and support for) cryptographic algorithms to use for authentication. (This option should only be used if requirements dictate use of the WWW-Authenticate header.)

Cryptographic Keys

The Neuron® uses public key cryptography to create auditable digital signatures. Such signatures are used both in eDaler® transactions in the wallet, but also on digital signatures on smart contracts, which form the basis of operation of Neuro-Feature™ tokens. Since such algorithms evolve and change over time, the Agent API helps clients manage and use such keys by providing the following resources. The clients therefore, do not need to implement each algorithm by itself, and can rely on the Agent API to manage the specifics of each algorithm.

• The GetAlgorithms returns an array of cryptographic algorithms the Neuron® supports, together with security-related information about each algorithm, such as security strength, and if the algorithm is safe or not.

• You create keys using the CreateKey method. You can freely create keys. You associate a Key ID with a private key. The Agent API implementation encrypts the information using a salted hash digest, initiated using a key password. This key password is not transmitted itself and therefore not stored on the Neuron®. This permits the Agent API to perform signatures on the clients behalf, but only when the client signs the corresponding request accordingly. Information for generating the signature is not persisted, and the Neuron® cannot therefore generate such signatures on its own. This is also why the API requires all calls including a cryptographic key the client provide the key password in the call.

Note: It is the responsibility of the client that calls the API to securely store the key password. Do not store the password in a way that permits other users to easily extract it. Use secure key storage when available.

• To be able to validate server signatures, you need to get server public keys. You do this calling the GetPublicKey resource.

Applying for a Legal Identity

Once you have a cryptographic key with which you can create digital signatures, you can apply for a legal identity. A legal identity is a collection of information (or meta-data) that can be used to identify a person (natural or legal), associated with the account. This association is cryptographically secured, and its integrity validated and protected, by means of the following process:

• The user initiates an application for an identity, using the ApplyId resource. This call associates a cryptographyic key with the collection of personally identifying meta-data to include in the identity.

  • To validate personal numbers, you can use the ValidatePNr resource.

  • To learn what identity properties are required for the application to be accepted, you can call the GetApplicationAttributes resource.

• If the Neuron® requires photos to be associated with the legal identity, you append the application with such photos as attachments using the AddIdAttachment resource.

• Once the application is complete, you call the ReadyForApproval resource, to flag the application as ready for approval. There are different types of approval processes available, depending on the configuration of the Neuron®:

  • The operator can approve (or reject) the application manually.

  • The Neuron® can use an integrated service for KyC (Know your Customer) that processes the application automatically, to determine if the application should be approved or rejected.

  • You can request a peer to review your application, if the Neuron® accepts use of peer review. You might need muliple peers approving the application, for the application to be approved. (For more details, see below.)

• Changes to the application will always be sent to the client asynchronously, as they occur. While the underlying communication framework uses XMPP (which is bi-directional and full-duplex) and push notification (using Firebase), Agent API is strictly a Request/Response-API based on HTTP (which is only half-duplex). This means you must poll the application to detect changes to it. There are two ways to do this using Agent API:

  • By calling the PopMessages resource, you can receive asynchronous messages that has been sent to the account since last call. This will include updates to any legal identity application object you have. It will also include other types of messages, for other types of objects, such as those related to tokens, wallet, etc.

    • Note: You may receive asynchronous messages from the reviewer indicating reasons for rejecting an application.

  • You can also call the GetIdentity resource directly, to get the information about a given identity object, given its identifier (which you get when you send in the application in the first place).

• Monitor the state of the identity object to determine next steps. Possible values are: Created, Rejected, Approved, Obsoleted and Compromised. Once it is Approved, you can use it to sign contracts and perform transactions. Once it is still Created, you need to continue to wait (until you choose to abandon application). If you receive Rejected, Obsoleted pr Compromised, you need to re-apply.

Requesting Review

Once an identity application is in the Created state, you can request others to review your application. You can send such applications to others, if you have their identifiers. The Neuron® may also contain a list of featured reviewers. The following resources are available for requesting peer-review:

• To gain access (optional) to identity reviewers published by the Neuron®, perform these steps:

  • Call the GetServiceProvidersForIdReview resource, to get a list of service providers and services that can perform identity application reviews. These may include human users (i.e. peers), as well as internal and external services for KyC. Each service will have an associated legal identity identifier that you will use when requesting review.

  • When selecting a service and service provider for reviewing your application, you need to select it. This is done by calling the SelectReviewService resource.

• Before sending a review request, you need to explicitly grant access to your identity application information to the reviewer, for them to be able to get access to the personal information in your application. This is done by calling the AuthorizeAccessToId. (You can revoke this permission using the same resource.)

• To send a request for review, you call the PetitionPeerReview using the legal identity identifier of the reviewer to indicate to whom to send the request. If you have also provided access to your information to that identifier, they will be able to review the application and return their decision accordingly.

Note: Information about the result of the review will be sent to you as an asynchronous message. The review will also be attached to the identity object, together with the identity of the reviewer, and visible to anyone who gets access to the identity. This allows auditors to be able to determine the validity of an identity, by permitting them to validate who have reviewed the application as well.

Once the identity object state becomes Approved, the identity is ready to be used, and the wallet is automatically created.

#agent, #api, #edaler, #recipe, #wallet, #account