Chainkit API

Authentication API

Chainkit uses JSON Web Tokens (JWT), and you'll authenticate to our token API with a username and password, which will return a JWT that your register, verify, and audit trail API requests will use in an Authorization header.

Token API

• Create a token for the user that will be passed in to register, verify, and audit trail API calls

• Creating a token requires a POST to the /token endpoint with JSON in the body containing your username and password

• POST /token

  • Requires username and password
  • Requires password (either plain text or encoded -- in this doc we'll show plain text but STRONGLY suggest you do not pass plain text production passwords)
  • Returns access token, refresh token, and expires in
  • The access token expires in 60 minutes.

Auth Token Flow

• Using the CURL command

curl -s -X POST https://api.chainkit.com/token -H \
'Content-Type: application/json' -d '{ \
    "username": "username", \
    "password": "password"
}'

• Sample response contains JSON with the JWT you'll use for requests to the register and verify apis

{
    "expiresIn":"3600",
    "accessToken":"eyJraWQiOiJ6emTux-tYgMzhYwHttvfw",
    "refreshToken":"eyJjdHkiOiJKV1QixZRMd6-k06ryD8wRC0Q8.cIQCg6BpmFIhSIoT-ubOTg"
}

Register API

• POST /register
  • Requires an Authorization: Bearer header
  • Requires JSON in the body of the message
    • Required fields:
      • hash (this is the crypto hash of your data that you wish to register)
      • storage -- options are public (Ethereum), Private (On-Prem Hyperledger), Pencil (High Performance Blockchain) or VMware (Concord) NOTE: The ETH test net is very slow due to high traffic, and we strongly recommend you only use 'private' storage for testing.
      • Example: { hash: lk334asdjfl3209djalksdf, storage: private }
    • Now support multi chains so storage can be multiple storage types (storage = public, concord, private)
      • For multi chain, the input must be a comma separated.
  • Returns an entity id for the registered hash once it has been stored in the blockchain
    • Tip: Do not lose this entity Id, we recommend storing it along with the metadata of your file or data that you hashed and registered. You'll use this entity Id and a fresh version of the hash to verify the data later.

Sample Register Workflow

• Register a digital entity

  Sample request:

   curl -X POST https://api.chainkit.com/register \
        -H 'Authorization: Bearer tewr6867tre254123gerw...' \
        -d { 'hash' : 'alskdjflaskdf32323', 'storage' : 'private' }

  Sample response:

  {"assetId":"6146776795971847947"}

  • The path parameter is the hash to register
  • The response is the asset id assigned to that hash
  • This request gets a transaction hash from the transaction receipt after writing into the ether blockchain ('storage = public')

Verify API

• GET /verify

• Verify a registered entity

  • Requires an Authorization: Bearer header
  • Verifies whether or not hash is the same as the stored hash for that entity ID
  • Returns true if the submitted hash for that entity ID matches what was originally registered, or false if there is no match
  • Note: Some hash or digests will put reserved http characters in the hash, which will cause a parsing and validation error. To avoid this, you should urlencode the hash before passing it to the verify API. Reserved characters from RFC 2396 include: ; / ? : @ & = + $, so if you think your hash might ever contain one of those characters, it's best (and just good practice) to urlencode it before sending it to our verify API.
  • Sample request

     curl -X GET \
     'https://api.chainkit.com/verify/1521192881643?hash=123AB4DF&storage=private' \
     -H 'Authorization: Bearer tewr6867tre254123gerw'

  • Sample response: true
  • The path parameter “1521192881643” in this example is the entity id of the asset to verify
  • The query parameter hash is the value of the hash to verify against the originally stored hash for the provided asset id
  • The Header Authorization: Bearer {{idToken}} is the token for the authenticated the user attempting to verify the hash.
  • If the provided user has appropriate permissions on an access policy for the provided asset and the provided hash matches the stored hash for the provided asset, returns true
  • If the user does not have appropriate permissions on an access policy for the provided asset or the provided hash does not match the stored hash for the provided asset, returns false
  • If users use the ether then the verify api also get a transaction hash from the transaction receipt.

Entity Ids API

• GET /getEntityId
  • Requires an Authorization: Bearer {{accessToken}} header
  • Returns all entity ids

Sample Entity Id API Workflow

• Sample request

  curl -X GET \
    https://api.chainkit.com/getEntityId -H 'Authorization: Bearer tewr6867tre254123gerw'

• Sample response

  [
    {
    "creation_date": "Tue Mar 16 07:09:22 UTC 2021",
    "storage": "pencil",
    "entity_id": "6358479363416465815",
    "transaction_hash": "asdfbvgRweqr"
    },
    {
    "creation_date": "Tue Nov 24 23:03:48 UTC 2020",
    "storage": "pencil",
    "entity_id": "6078716591386968531",
    "transaction_hash": "qwklqrwiEHwi"
    }
  ]

  • There are no parameters required but decoding the access token filter with the username and showing this user's results.
  • All entity Ids are retrieved by the given username from the access token.

Logs API

• GET /getLogs
  • Requires an Authorization: Bearer {{accessToken}} header and the registered entity id
  • Returns all logs for the given entity id

Sample Audit Log API Workflow

• Sample request

  curl -X GET \
    https://api.chainkit.com/getLogs/{entityId} -H 'Authorization: Bearer tewr6867tre254123gerw'

• Sample response

  [
    {
     "verified": "True",
     "creation_date": "Fri Jan 29 23:21:51 UTC 2021",
     "storage": "pencil",
     "entity_id": "5635723255437431455",
     "transaction_hash": "akhiekIKEMfn"
    },
    {
     "verified": "False",
     "creation_date": "Fri Jan 28 23:20:50 UTC 2021",
     "storage": "pencil",
     "entity_id": "5635723255437431455",
     "transaction_hash": "GJkemmhfdhLFJjd"
    }
  
  
  ]

  • The access token is required and the registered entity id is also required.
  • Returns all audit logs so we can check each information including past results.