Using a proxy server with Agent API & Quick Login API

From build 2025-02-05, a new mode is available for integrating Quick Login API and Agent API when using a proxy to access the Neuron®. The web page may reside on an external server, and it wants to integrate with both Quick Login API and Agent API on a Neuron® different from the web server. In this case, the web-client only or backend modes are not sufficient, as they cannot integrate the two APIs seamlessly. Session mode is not available either, since the HTTP session held by the client, is between the client and the web server, not the Neuron®.

A new mode is now availble: A Session-proxy mode. allows the client to create a Session ID implicitly, by adding a agentApiTimeout property in the initial request made to the Neuron® from the proxy. The Neuron® will implicitly call the QuickLoginServiceId(Request,Timeout) function, and return the Service ID in the response to the proxy.

Note: The proxy needs to enable cookies in its communication with the Neuron®, to maintain the session correctly. The proxy will need to call the Agent API over the same session, to be able to access the Quick Login done in this mode.

For more information, see the Quick Login API reference documentation.

#new, #features, #neuron, #agent, #agentapi, #quicklogin, #api

Agent API C# implementation

A C# implementation of the Agent API is now publicly available both on Github and as a NuGet Package

The implementation provides generated models and simplifies the process of making requests to the Agent API for .NET applications

Instructions and documentation can be found on the Github page. Also feel free to open any issues on the Github page

#c#, #.net, #agent, #api, #agentapi

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

Creating a Neuro-Feature token on credit using AgentAPI

This article describes how you can use the Agent API to create Neuro-Feature™ tokens on credit. It assumes you already have an account, and a wallet created. The wallet will receive the tokens created, as well as receive the credits required to pay for any token creation fees required. If you do not have an account with a wallet, check out the recipe Creating a wallet using Agent API.

The process is as follows:

• A smart contract template is created and approved. The purpose of the template is to define how tokens are created, and their legal context.
• A smart contract is created based on the approved template.
• Neuro-Credits™ are bought, to generate sufficient eDaler® in the wallet to create the tokens.
  • Invoices with reminders are sent to the e-mail registered for the account.
  • Payment of invoices can be done at a later stage (before the due-date) on the links provided in the e-mails.
• The contract is signed. This casues a series of events:
  • The token generation process to start (if contract successfully approved, and not failed).
  • Funds required to create the token or tokens are withdrawn from the wallet.
  • The created token or tokens are received in the wallet.

Creating a smart contract template for token creation

The creation of smart contract templates is done outside of the scope of the Agent API. It is typically a development process, where token developers generate the template in some form of tool, such as LegalLab, and publish the templates on Neurons. Once the templates have been approved by the Neuron® operators, they can be the basis of creating smart contracts using the Agent API. When creating a smart contract based on a template, you can change the parties that sign, and the parameter values, within the valid ranges defined by the template, but you cannot change the underlying definition of the token, or any human-readable sections or validation rules of the smart contract template.

Note: The LegalLab repository contains many examples of templates for creating Neuro-Feature™ tokens. These can be used for development purposes, and for testing the concepts described in this article.

Creating a smart contract for token creation, based on a template

When automating the creation of smart contracts based on a smart contract template, you typically need the following information:

• A Contract ID for the template.
• What Roles are defined in the template, and how many are needed of each for the contract to become valid.
• What Parameters exist, and their types and valid value ranges.

This information is readily available from the template itself, and it may vary from template to template. It can also be provided by the developer of the template. But there are some roles and parameters that will occur frequently, if they are not hard-coded into the contract template itself. They are provided here, for reference:

Common Roles
Role	Use	Description
Creator	Required	The creator of the token. The party that signs the contract as a Creator pays the fees required to create the token or tokens. This would be the Agent API client, in the example of this article.
Owner	Optional	If the template allows the owner to be different from the creator, the party that signs as Owner will receive the created tokens in their wallet.
TrustProvider	Required	This role is reserved for the Neuron® itself. The Trust Provider is the party that permits the creation and hosting of the token, and assures the integrity of the token, as well as protects the confidentiality and privacy of the associated information.
Valuator	Optional	A party that attests to the initial value stated for the contract.
Assessor	Optional	A party that has provided necessary input in the creation of the token.
Certifier	Optional	A privileged role albeit external role of a token. They can certify to the correctness, legality, contents or context of the token. They can also be given special privileges with control over the life-cycle of the token (meaning, if the token definition permits it, they can kill the token if compliance quirements are not met).
Witness	Optional	A witness to the signature and creation of the tokens.

Common Parameters
Parameter	Use	Type	Description
Value	Optional	Numeric	The initial value of the token.
Currency	Optional	String	The currency of the token.
CommissionPercent	Optional	Numeric	The number of percent of the value that needs to be paid by the creator, for the creation of the token or tokens.

Note: There may be other parameters available that are required, depending on the type of token that is to be created. Check with the creator of the token definition to get a detailed list of parameters required to be set.

Getting token creation attributes

The Currency and CommissionPercent parameters that will be accepted by the Neuron®, as well as the Legal Identity identifier for the TrustProvider Role, can be retrieved by calling the GetCreationAttributes resource using the Agent API. After retrieving these values, you can preset the parameter values accordingly.

Buying Neuro-Credits™

When you know the amount of eDaler® that is required to create a token, or the tokens, you can generate eDaler® on credit, by buying Neuro-Credits™. You can also generate more eDaler® than the token creation requires, and use it for multiple operations, to save on invoicing fees. Use the following resources in the AgentAPI to manage eDaler® in the wallet:

• To get the current balance of the wallet, call the GetBalance resource.

• To generate eDaler® in the wallet, you buy eDaler®. To see options available for buying eDaler®, call the GetServiceProvidersForBuyingEDaler resource. It will present configured options available for your choice of country and currency. Some of these providers are contract-based (i.e. they are initated by signing a smart contract with relevant information), and some are initiated by collecting information from the user via an external web page.

  • If you already know what service provider you want to use, like in the case for using Neuro-Credits™, you can skip this part. The Service Provider ID in this case is TAG.Payments.NeuroCredits, the Service ID is TAG.Payments.NeuroCredits.NeuroCreditsService, and the ID of the smart contract template for initiating the process is 2cdbfa69-6c21-82d9-880e-301af77b53f6@legal.paiwise.tagroot.io (at the time of writing; you might want to double-check this regularly).

  • To initiate the process of buying eDaler®, you can call the InitiateBuyEDaler if the service collects information from external web pages. If the process is started via smart contracts (like in the case for Neuro-Credits™) you simply create and sign a smart contract based on the template provided for the service.

    Following is some information required to create a smart contract for buying Neuro-Credits™:

    Defined roles
    Role	Description
    Buyer	The one buying eDaler®, i.e. the Agent API client.
    TrustProvider	The Neuron® itself, giving the credit to the buyer.

    The following parameters need to be provided:

    Required parameters
    Name	Type	Description
    Amount¹	Numeric	Amount of eDaler® to buy.
    Currency²	String	Currency to buy.
    InvoiceFee³	Numeric	A fee for each invoice that is sent.
    Message	String	A text message that will be included in invoices sent to the client, for reference.
    Period³	Duration	The duration of the credit, or the time between installments, if multiple installments are used.
    PeriodInterest³	Numeric	The interest rate of the (remaining) amount, calculated over the period.
    Installments4	Integer	Number of installments desired.

    Some of the parameters are limited in range, and some must be set to a fixed value, depending on the configuration of the Neuro-Credits™ service on the Neuron®. To get these values and ranges, you call the GetServiceProvidersForBuyingEDaler resource:

    1. Amount is restricted to the maximum remaining credit allowed to the client.
    2. Currency must be the same as defined in the wallet of the client.
    3. The fees, period and interest rates are fixed by the service.
    4. The amount of installments allowed may vary on client.

    Note: A smart contract with parameters outside of the authorized ranges will fail the contract.

    The following parameters will be required to exist in the legal identity of the buyer, and will be visible to auditors of the contract, if a personal credit is requested:

    • Full Name
    • Personal Number
    • Full Address
    • Postal Code
    • City
    • Country

    If an organizational credit is requested, the following additional information must be available in the legal identity of the buyer. This information will be visible to auditors of the contract:

    • Organization Name
    • Organization Number
    • Department
    • Role
    • Organization Address
    • Organization Postal Code
    • Organization City
    • Organization Country

    Additional information that may be required include an associated e-mail address and phone number of the client. These will not be engraved into the contract however, for privacy reasons, and only be available to the operators of the service.

    Once the parameter values have been determined, you create the smart contract by calling the CreateContract resource, and then sign it using the SignContract resource. Once everyone has signed the contract except the Trust Provider, the contract is analyzed, and the Neuron® signs as Trust Provider given that all parameters are correct. If information is incorrect or the process fails, the contract will be set to a Failed state, otherwise the contract will be set to a Signed state and the corresponding eDaler® will be generated and placed in the wallet of the client. Al lasynchronous processes generate messages sent to the client, which the client can read by calling the PopMessages resource.

Note: Any changes to the balance of the wallet, or transactions being performed, are notified to the client asycnrhonously (i.e. as they happen). You can use the PopMessages resource to retrieve all such asynchronously sent messages to you.

Getting the human-readable text of a smart contract

The GetContract resource allows you to get the contents of a smart contract (that you have access rights to). If you want to present the contents of the contract to the user, you have to choose if you will render the contents, based on the existing object-model for human-readable text, or if you want the Nueuron® to format it for you. The default is to let the client render the contents in its own way. If you provide a value in the Format argument, in the call to the GetContract resource, you can get the human-readable texts pre-rendered instead in the corresponding format. The following formats are supported (at the time of writing):

Human-readable text formats
Value	Format
Markdown	Texts are returned in Markdown format. Markdown is easy to edit in text editors, and can be transformed to any of a series of other formats.
Html	Text is converted to HTML for insertion into existing HTML (i.e. it does not include HTML, HEAD and BODY tags.)
Text	Contents is converted to plain, unformatted text.
Xaml	XAML is generated for use together with Windows Presentation Foundation (WPF).
XamarinXaml	A special dialect of XAML, for use in Xamarin Forms, is returned.
SmartContract	An XML string containing the contents using the smart contract object model is returned.

Signing smart contract to create tokens

When it is time to sign the contract, you call the SignContract resource for each signature you perform. You will sign the contract using the legal identity referred to in the call, and using the associated key. A contract becomes signed when all required signatures have been provided.

When then smart contract is to create a Neuro-Feature™ token, one of the roles is that of a Trust Provider. This role is reserved for the Neuron® itself, and represents the party that will host the token. Typically, a smart contract for token generation includes at least a Creator role, and often (but not always) an Owner role as well (if different from the Creator. If no Owner role is available, the Creator becomes the initial Owner.

When all signatures, except then Trust Provider has signed, the Neuron® validates the contract and signatures, and if all is OK, signs the contract itself. Once the contract has been signed, the token creation process begins. In this step, if the Neuron® detects there are missing funds, or other prohibited content is detected within the token itself, the contract becomes failed, and a message is sent to the creator.

Note: All changes to the contract, and generated token or tokens are notified to the concerned parties asynchronously. Use the PopMessages resource to receive such notification messages.

Transferring ownership of token

Once a token is created and alive, it can be transferred to a new owner. Such a transfer is basically a contract in itself. In this contract, the prospective new owner (or buyer) agrees with the current owner (or seller) to transfer the token from the seller to the buyer, and transfer an agreed amount of eDaler® from the buyer to the seller. The amount of eDaler® transferred is logged on the token itself, and visible to future buyers, and acts as the basis for the current value of the token.

The LegalLab repository contains example contracts for transferring ownership of a token between owners.

Note: The process of creating a transfer contract, and signing it, is the same as creating the token in the first place: You refer to a template when creating the contract, providing the corresponding parameters, and sign the contract accordingly. The Neurons take care of the rest.

#agent, #api, #neuro-feature, #credit, #edaler, #recipe, #legallab

Agent API Postman Collection

A first version of a postman collection for the agent API is now available at https://github.com/Trust-Anchor-Group/AgentApiPostman

Postman can be downloaded here https://www.postman.com/

Postman is a great tool for testing API endpoints and allows you for example to run pre-request scripts and automatic test scripts on the responses. The environment and variable tools allow you to save data and variables between tests, so the contract ID can for example be automatically saved after creating a contract via the Create Contract request and be automatically used in signing requests without manually copying and pasting.

Further instructions can be found in the readme of the repository. The collection is not complete, a table showing which endpoints are currently available can also be found in the readme.

#agent, #api, #postman, #collection