Table of Contents
  1. Repositories
  2. API Keys
  3. Content-Types
  4. Resource Names
  5. Methods
  6. Encryption
  7. Pattern Matching
  8. Return Codes
  9. Authentication
  10. Resources
    1. Accounts
    2. Xmpp
    3. Storage
    4. Cryptography
    5. Legal
    6. Wallet
    7. Tokens
    8. State Machines
    9. Open Intelligence
  11. Javascript Library
  12. A Note on Keys in Cryptography

Agent API

The Neuron® publishes an Agent API that can be used by agents that do not wish to, or are able to, connect to the Neuron® via any of the XMPP bindings available, such as standard binary socket, websocket or Synchronous HTTP (BOSH). Via the Agent API, the agent is permitted to do basic tasks, such as send messages, create Agent IDs, and sign contracts with such Agent IDs. The Full API is available via XMPP.

Repositories

Following is a list of repositories related to the Agent API, that you can use to simplify use, integration and development of and with the Agent API:

API Keys

To create an account, you will need an API Key and a Secret, which the operator of the Neuron® provides. You can contact the operator through the feedback page on the corresponding neuron https://DOMAIN/Feedback.md, or go directly to the Request API Key page on the Neuron® https://DOMAIN/RequestApiKey.md.

Content-Types

Content-Types of input and output is controlled by Content-Type (from client to server) and Accept (from server to client) respectively. Requests must use these headers for the correct processing of requests, even if only one Content-Type is supported at the moment of implementation. The reason for this is that resources may be extended over time to support multiple types of data representation.

Common Content Types:

Content-Type Description
application/json JSON-encoded text.
text/plain Plain text.
text/xml XML document.

Resource Names

All resources published by the API are published under the root folder /Agent. The resource /Account/Login is therefore accessible via https://DOMAIN/Agent/Account/Login.

Methods

Unless otherwise stated, resources are accessed using the HTTP method POST.

Encryption

All requests require transport encryption (TLS) of at least 128 bits, unless on a developer machine (i.e. a machine without a configured domain).

Pattern Matching

Input content is described using assignment pattern-matching script syntax, for simplicity.

Return Codes

Requests to resources will return an HTTP responde code. Following are the most common response codes that can be returned:

Code Description
200 Request processed OK.
400 Bad request, most probably due to the content sent in the request not conforming to the specification.
401 Unauthorized access to a resource was prevented. Client must login first.
403 Forbidden access to resource was stopped. Client does not have sufficient privileges to access resource or perform requested action, or access is done using unencrypted, or a connection that is not sufficiently encrypted.
404 Resource, or item referenced in request, was not found.
405 Method not allowed. A resource was accessed using an HTTP method not supported by the resource.
406 Content sent, or content requested in a format that is not supported by the resource.
429 Too many requests have been made, for this resource, or any of the referenced resources in the request.

Authentication

Most resources require the client to be authenticated. Exceptions to this rule are the /Account/Create, /Account/Login, and the /Account/Login resources. The other resources require the client to provide credentials authenticating the client. When creting an account or logging in using the API, a JSON Web Token (or JWT) is returned. This can be provided as a Bearer token to authenticate the client. This is the simplest method with sufficient level of security, as it does not require two HTTP request/response messages to be completed for each API request. Other authentication mechanisms are available as well. These are typically important for the /Account/WwwLogin call. See the HTTP Response header for more information on the mechanisms available. Note that encryption is required for all calls.

Resources

In the following subsections, Agent API resources are listed and described.

Accounts

Xmpp

Storage

Cryptography

Wallet

Tokens

State Machines

Open Intelligence

Javascript Library

The Agent API can be accessed via a Javascript API available on the Neuron®. All you need to do to access this library, is to include the Javascript file /Agent.js in your webpage. You download it from the Neuron® you wish to access. (You can also review the code via the public GitHub Repository AgentApiJavascript.) If the web page is defined in Markdown, you simply add the following header:

JavaScript: /Agent.js

Some of the functions have the option of reporting back to the client via asynchronous events. Such can be either polled, via the API, or received immediately, by including the Javascript file /Events.js. The functions that support this, clearly indicate if support for such push notifications are available. If the web page is defined in Markdown, and you wish to receive such asynchronous events, you simply add the following header:

JavaScript: /Events.js

The Agent API is available to your code via an object called AgentAPI. The following asynchronous methods are available. All API resources are transparently linked to the this Javascript object model, using similar names and parameters.

Note: The Javascript library also adds additional functions, that internally call the other functions to perform the corresponding actions. (For example, the AgentAPI.Legal.SendProposal function calls the AgentAPI.Xmpp.SendXmlMessage function to send the actual message. There is no corresponding /Legal/SendProposal web resource defined in the Web API.) Such functions are annotated below, with a red .

A Note on Keys in Cryptography

The Agent API helps clients to perform the cryptographic tasks involved when applying for digital identities and signing smart contracts. For these cryptographic methods to be performed securely, the client must be the only party that knows the private key. To avoid operators of the server to sign in the name of the client, all keys managed by the Agent API are stored salted and encrypted, protected by key passwords, only held by clients. For this reason, the API works with two kinds of passwords: One for accessing the account, and one for each key generated. Any operation that requires a cryptographic signature to be performed therefore also require special key and request signatures to be performed. The reason for this, is that these passwords generate the keys necessary for the server to decrypt the private key information sent to it by the client. Once decrytpted, they can be used to generate the signature, before being forgotten again, until the next call. These private keys are never persisted in clear-text, and cannot be unlocked by any practical means, without the successful authentication using these credentials.