The developer portal is a rich CMS with built-in app registration, support for automatic API key approval, and an API management layer.

BlockID For Developers


Below are a few examples of our API endpoints, requests, and responses. These examples use twurl—a command-line application that can be used to make authenticated requests to the platform. twurl is like curl, except that it abstracts away OAuth details once you configure it with your keys.

API Endpoints (decrypted) JSON Examples

Method : HTTP-POST
{
  "aps": {
    "alert": {
      "title": "Voice Biometrics Demo Server",
      "logo": "https:\/\/blockchainidentity.ca\/images\/logo.png",
      "body": "Blockchain Identity KYC account creation request from BlockChainIdentity.ca",
      "loc-key": "https:\/\/blockchainidentity.ca"
    },
    "sound": "chime.aiff"
  },
  "APNS_ImageURL": "https:\/\/blockchainidentity.ca\/notification.jpg",
  "authz-type": "voice",
  "sessionID": "TzVCNzhGQVNIREJWSTUxM1JGSkhEVFQyNlVVVEJVOERDUFVPNDRDNE02MExSVTdU",
  "scopes": "firstname,lastname,address,phone,dl,ppt"
}
Method: HTTP-GET
Request :
{
}

Response : 
{
   "@context": "https://w3id.org/did/v1",
   "id": "did:blockid:Cf69C0d49434C091508dc81C103d90fE28D09A55",
   "publicKey": [{
      "id": "did:blockid:Cf69C0d49434C091508dc81C103d90fE28D09A55#keys-1",
      "type": "RsaVerificationKey2018",
      "owner": "did:blockid:Cf69C0d49434C091508dc81C103d90fE28D09A55",
      "publicKeyPem": "-----BEGIN EC PUBLIC KEY-----
                       MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEHG2b0e5y/jZ/OhaALU509VtkNC49VE6/
                       OZT8+/va0sxP+sHg+ZwOeaa49EmFUOIddlHVwjpeq9j8tX5glwToKw==
                       -----END EC PUBLIC KEY-----"
   }],
   "authentication": [{
      "type": "RsaSignatureAuthentication2018",
      "publicKey": "did:blockid:Cf69C0d49434C091508dc81C103d90fE28D09A55#keys-1"
   }],
   "service": [{
      "type": "AuthenticationService",
      "serviceEndpoint": "https://api.blockchainidentity.ca/auth/TzVCNzhGQVNIREJWSTUxM1JGSkhEVFQyNlVVVEJVOERDUFVPNDRDNE02MExSVTdU"
   }],
   "claims": [{
      "firstname":"Susan",
      "firstname":"Welsh",
      "address":"360 N Martel Ave, Los Angeles, CA 90036",
      "gender":"F",
      "Passport":[{
		"DocumentNumber":"431276122",
		"Nationality":"USA",
		"Opt1":"712013065",
		"DateOfBirth":"1971-04-01",
		"DateOfExpiry":"2030-04-01",
		"Issuer":"USA"
      }],
      "Drivers License":[{
		"City":"Los Angeles",
		"JurisdictionCode":"CA",
		"PostalCode":"90036",
		"AddressStreet1":"360 N Martel Ave",
		"Country":"USA",
		"IDNumber":"000000900",
		"DateOfBirth":"1971-04-01",
		"IssueDate":"2017-04-01",
		"DocumentType":"AAMVA",
		"EyeColor":"Hazel",
		"Height":"163",
		"IssuerIdentificationNumber":"ASDE44325667893",
		"VehicleClass":"B",
		"PaymentDataType":"US"
	}],
   "IAL":"3",
   "AAL":"2"
   }]
}
Method: HTTP-POST
Request :
{
  "sessionID": "TzVCNzhGQVNIREJWSTUxM1JGSkhEVFQyNlVVVEJVOERDUFVPNDRDNE02MExSVTdU"
}

Response :
{
  "retCode": 100,
  "retMsg": "Success"
}

API Response Error Codes

1Kosmos BlockID uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a response code of 2xx or 3xx indicates the operation was successful. Other error codes indicate either a client error (4xx) or a server error (5xx).

Status Code Status Description
200 OK - Response to a successful GET, PUT, PATCH or DELETE.
201 Created – Response to a POST that results in a creation.
304 Not Modified - Response to a successful request that won't be returning a body (like a DELETE request).
304 Not Modified – Response has not been modified since the previous transmission.
Error Code Error Description
400 Bad Request – Check the response ‘message’ field for details.
401 Unauthorized – Authentication failed.
402 Payment Required - When payment check has failed..
403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource.
404 Not Found - When a non-existent resource is requested.
405 Method Not Allowed – You tried to access an invalid method.
406 Not Acceptable – Could not satisfy the request Accept header.
409 Conflict – When the request could not be completed due to a conflict with the current state of the resource.
415 Unsupported Media Type – Unsupported media type in request.
429 Too Many Requests – Your request was throttled by our gateway.
500 Internal Server Error – We had a problem with our server. Try again later.
504 Endpoint Request Timed-out Exception.

Security Requirements

In a standard 1Kosmos BlockID deployment, certificates provide the underlying support for the authentication, integrity, and confidentiality of messages exchanged between the various platform components, as well as any federated partners communicating with BlockID. These certificates play an important role in the BlockID federated security model in that BlockID uses them to sign and encrypt the Assertions and the security tokens issued by the BlockID Security Token Service (STS), which are then validated/decrypted by the various services and applications deployed against BlockID. There are two important types of certificates used in an BlockID deployment, the Server Certificate and the SSL Certificate.

Server Certificate

When you install BlockID, you must select a "Server" certificate as part of the installation process. This certificate is used by the BlockID STS to encrypt the security tokens issued by it each time a user authenticates against the system and used by the BlockID services to verify the validity of those tokens and the access requests represented by them. As this is the case, you must have the private key for this certificate as it is used by the BlockID services to decrypt the tokens passed to them by the STS.

The Server certificate must be issued by a Certificate Authority in the Trusted Root Certification Authorities of the local machine and meet the additional requirements:

  • It must be valid
  • It must be deployed in the Certificates (Local Computer)\Personal store
  • Minimum intended purpose includes Client/Server Authentication and Encryption

Certificate Requirements

Each BlockID Service has the following certificate requirements:
  • Private Key Certificate (for all services) - The private key is owned by the service to decrypt the security token and to generate the XML digital signature to ensure integrity and source verification.
  • Public Key Certificate (for all services) - This allows each service to communicate with the other services and is used to establish trust and encrypt the security token.
  • Public Key Certificate (for all issuers) - This allows any issuer to be used in a federation.
  • Root Certificate for CA

Certificate Compliance

Due to the different types of certificates that could be used, BlockID performs its own validation to ensure a deployed certificate meets the minimum requirements. This validation takes into account self-signed and certificate-authority issued certificates within the issuing chain. Although BlockID does not support the Peer or Chain trust, you may elect to use these types of certificate validations in your client applications. Where a certificate used by the client application is deployed is irrelevant to the BlockID Web Role Server or the service being consumed by the client application. If you choose to use the Peer trust validation, your certificates must be deployed in the Trusted People store for your client application to work.

Blockchain Identity

Identity is tied to individual users on the distributed ledger idenfified as accounts. Accounts hold the associated data of the individual as encrypted metadata, but more importantly, there are a few cryptographic elements to associate and authenticate the individual to the account.

An account consists of the following elements:

  • An elliptic Public key
  • An address
  • A node key of the hosting account.
  • An ISO timezone code
  • An arbitray key-value metadata store of encrypted personal information (name, address, identity assurance level, etc)
It is uniquely identified by its elliptic curve key pair (Public and Private key) as well as its address. The address itself is derived from the Public key of the account. The key pair is generated using elliptic curve secp256k1.

Private Keys

An elliptic curve private key is the private integer that generates the public key of elliptic curve multiplication with the chosen curve’s base point. All information for a user account can be derived from the private key.:

-----BEGIN EC PRIVATE KEY-----
MHQCAQEEICbWyFXHqbJ4AkCroGfkkmtZmaxEtDHjIHgB9yi1VbzpoAcGBSuBBAAK
oUQDQgAEHG2b0e5y/jZ/OhaALU509VtkNC49VE6/OZT8+/va0sxP+sHg+ZwOeaa4
9EmFUOIddlHVwjpeq9j8tX5glwToKw==
-----END EC PRIVATE KEY-----

Private keys can also be layered with additional layer of protection in which the key body itself is encrypted with a passphrase and then EDE3 encrypted, requiring the user to supply the phrase before using the key.:

-----BEGIN EC PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
EK-Info: DES-EDE3-CBC,BE261F2652B3D42D
MHQCAQEEIFzLhwiyvt76NlYgGbpzPlV3FQk8ZEnZ7loxmRYnzPKzoAcGBSuBBAAK
oUQDQgAEBbEN3tve82UYi+UOI3JbDKHnbVyNq7SqCaTCHGgYodcBvp3eQEWcZdO/
XW2hfHV0XAcxVdgEBzgpwkBUpXoZIQ==
-----END EC PRIVATE KEY-----

Public Keys

The public key is the compressed point stored as the binary representation of the x and y coordinates of the elliptic curve point compressed and base64 encoded.:

-----BEGIN EC PUBLIC KEY-----
MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEHG2b0e5y/jZ/OhaALU509VtkNC49VE6/
OZT8+/va0sxP+sHg+ZwOeaa49EmFUOIddlHVwjpeq9j8tX5glwToKw==
-----END EC PUBLIC KEY-----

Keys given through the SDK access are specified in hexadecimal form, in which a 128 character string encodes the public key, the first 64 bytes are the first coordinate:

pub = af0b33d9e8af2b771200a87012fc6aa07b391d8ac01b40975359a7d35d38f13b9d1d65b28a9a1a413436cf6dc5bafcb551a4953b8f30c751d111262ed07a13fd
pub_x = af0b33d9e8af2b771200a87012fc6aa07b391d8ac01b40975359a7d35d38f13b
pub_y = 9d1d65b28a9a1a413436cf6dc5bafcb551a4953b8f30c751d111262ed07a13fd

Metadata

A given account in the system can be associated with an associating list / dictionary mapping small keys to small pieces of metadata that are relevant to application-specific uses of an account, allowing users to publicly specify data about their identity which is available to all participants.

Revocation Certificates

An account within the BlockID network can be revoked via a Revoke Account transaction. Once accepted in a block, the Revoke Account transaction will remove an account from the ledger such that all future blocks or transactions issued by that account will be recognized as invalid by all nodes in the network.

Address Derivation

BlockID users have unique addresses that correspond to their identity. These addresses are derived as the SHA3-256 hashes of their public key point. With the key generation system, the number of possible private keys is 2256 and given sufficient random generation, duplicate keys and addresses are computationally intractable to construct. This systems gives every user, and all possible future users, a universally unique address to interact and sign transactions with that can be held in secret. The derivation of an address follows:

A private private key is a single random number that when combined with the base point G of the curve produces a point which is used as the public key.

98296211651717299139762843134195246423141641269875149366667447906894933497213

The public key consists of an (x, y) point on the elliptic curve.

24743765458702092737859495507479160116323479469637210741369089466842052538073
64340202121781598379555822771472089499346994701940280771055750875585295372717

The address itself is derived by converting the two integers into a byte array by concatenating the byte representation of the x and y points and then repeatedly hashing the result to produce a single unique number.

The hashing function then is applied:

Given the public key point above the resulting hash is the represented as a base58 encoded bytestring, which uniquely identifies the participant on the network.

HemEv9ukwoFSr11XYaKxdmpGVo2cPEbx8csqnD8NSn9gcZAGTtGg5JZQb68B

Base58 Encoding

Base58 is a group of binary-to-text encoding schemes used to represent large integers as alphanumeric text. It is similar to Base64 but has been modified to avoid both non-alphanumeric characters and letters which might look ambiguous when printed. It is therefore designed for human users who manually enter the data, copying from some visual source.

123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
Developers Portal Access
 
Remember me


Access Restrictions

Partners have access to our test environments via environment specific clientID’s and API keys. ClientID’s and API keys can be managed in the developers portal. It is possible to generate multiple API key's for the same ClientID.

Our API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. API requests without authentication will also fail.


Browser Support

Please ensure your cookies and Javascript are enabled. The platform supports use of current releases of the following web browsers:


Demo Sites

Voice Recognition Demo


Face Recognition Demo


KYC & AML Demo


MFA for AAL3 & IAL3 Demo