Get an API Key

To develop with the Identity Service, you need to register for an API Key by contacting [email protected].

Please provide us a GPG key we can use to encrypt the API key credentials, or any secure way to transfer you this information.

Authenticate requests with API Key

Use your application API Key to authenticate all requests you perform on the Identity Service API. This is done in the HTTP Authorization header as BASIC scheme. The client ID is the username and the secret is the password. Basic authentication must be Base64 encoded.

Authorization: Basic Base64(client_id:client_secret)

Creating and updating identities

As of today, only identity owners are able to create an Identity for their own usage, and to update their information (excluding claims).

Identity meta-data

Meta-information are composed of identity deployment status, ONCHAINID contract address, handle and description.

Retrieve identity meta-data

To retrieve identity meta-data, your API Key must have the READ_ID_METADATA permission and access to the identities you are querying.

This route is useful to know if an identity was deployed, and to get the ONCHAINID address of an identity if you know its ID. It's also used to get the identity ID from the ONCHAINID address.

API Page

GET {{endpoint}}/identities/{{identityId or ONCHAINID address}}

Response (application/json)
{
  "id": <UUID>,
  "handle": <string>,
  "address": <ethereum address string>,
  "description": <string>,
  "status": <NOT_DEPLOYED / DEPLOYING / DEPLOYED>
}

Identity information

The Identity Service stores arbitrary information for identities. Information are updated by the identity owner, or by application with explicit delegation on their identity.

Information history is kept, and are always accessible to application authorized to access previous version of an information value.

An information is composed of:

• A key: to identify the information.
• A schema: that defines the format of the information value. Information must comply to their schema to be able to be stored. Some information key expect a standard schema.
• A value: that complies to the information schema. The value can be a string, a number, an array, an object, or even files.

Retrieve identity information

To retrieve identity information, your API Key must have the READ_INFORMATION permission and must have access to the identity.

You can specify what information (and their version) you want to retrieve on the identity in query parameters. As a convenient method, you may also perform a POST request with, in body, the description of the information you wish to retrieve.

For the GET information method, information keys are specified in the example below and respect this format: ?keys=<key>,<version>&keys=<key>,<version> (keys is a query array of key and version pairs separated by comma). Use latest as the version to retrieve the latest version of the information value. Use all to get the full history of the information.

Each information queries is returned, if it exists on the identity, as an array of requested versions of te value. The array will contain the latest value only if specified with latest.

API Page for GET information
API Page for POST search

GET {{endpoint}}/identities/{{identityId or ONCHAINID address}}/information
?keys=<key>:<version>

Response (application/json)
{
    "<key>": [
        {
            "value": {
                "country": "ESP",
                "state": "kjh"
            },
         		"schema": {
                "properties": {
                    "country": {
                        "type": "string",
                        "minLength": 2
                    },
                    "state": {
                        "type": "string",
                        "minLength": 2
                    }
                }
            },
            "date": "2020-03-05T14:44:00.585Z",
            "version": "<version>"
        }
    ]
}