The original Tierion application will continue to be available to existing customers. Learn more >

Hash API Documentation

Using the Hash API

To use the Hash API, you will need to have a Tierion account. If you do not have an account, please signup for an account before getting started. We welcome your feedback and suggestions.

HTTPS is required for all requests.

Client Libraries

Tierion's Hash API client libraries help you get your project started faster by providing helper functions to manage authentication and make API requests.

We currently offer a client library for Node.js users. If you'd like to see a library for your language of choice, or have developed one of your own, let us know!

Official Tierion supported libraries:

Node.js package - https://github.com/Tierion/hashapi-lib-node

Community supported libraries:

Ruby gem - https://github.com/grempe/tierion - by Glenn Rempe

Authentication

Tierion's Hash API uses a JSON Web Token as an access token for authentication. Every request must include a valid access token.

Hash API requests must contain the following header:

Authorization: Bearer _your_valid_access_token_goes_here_

To obtain your access token, submit your Tierion credentials to our token endpoint.

POST https://hashapi.tierion.com/v1/auth/token

Parameters

Name Description
username The email address you use to log in to Tierion. [Required]
password The password you use for your Tierion account. [Required]

Request Sample

POST   https://hashapi.tierion.com/v1/auth/token
{                                 
  "username": "pgibbons@initech.net",                                 
  "password": "ilovekungfu"
}

Response Sample

Status: 200 OK
{
  "access_token": "eyB9eXAiOiJKV1QiLDJhbGciOiJIUzI1NiJ8.eyJpZCI6IjU2ZyyiYzFhNWY5Yjg1MjMyZmRjYWRhNyIsInJsbiI6MjBwMCwicmxpIjoicyIsImlzQWRtaW4iOnRydWUtImlhdCI6MTQ2MTI0NzE2NSwiZXhwIjoxNDYxMjUwNzY1LCJqdGkiOiI1MDUyYmFlZDhkNTM5NjcyNDNiMjkzN2RjNjRjNTcyOTJmNTQwZDZhIn0.KNiG-QHdeaH1jVLJpx0ykov8Kk7ogts69k5OhDkgFVM",
  "expires_in": 3600,
  "refresh_token": "ec71236f77ebd665210912ae8891aa08ee8ec3e4"
}

Access tokens are valid for a period of one hour. The 'expires_in' value displays the token lifespan in seconds. To obtain subsequent access tokens after your first one expires, you do not need to resubmit your Tierion credentials to our token endpoint. Instead, you can submit your refresh token to our refresh token endpoint. The refresh token endpoint will return a new valid access token.

POST https://hashapi.tierion.com/v1/auth/refresh

Parameters

Name Description
refreshToken The refresh token you received with your first access token. [Required]

Request Sample

POST   https://hashapi.tierion.com/v1/auth/refresh
{
  "refreshToken": "ec32176f77ebd556210912ae8891aa08ff8ec3e4"
}

Response Sample

Status: 200 OK
{
  "access_token": "eyoJAxeiOiJKV1QiLCJhbGciOiIUJzI1NiJ9.eyJpZCI6IjU2ZWRiYzFhNWY5Yjg1jMjyZmRjYWRhNyIsInJsbiI6MjAwMCwicmxpIjoicyIsImlzQWRtaW4iOnRydWUsImlhdCI6MTQ2MTI0Nzk5NCwiZXhwIjoxNDYxMjUxNTk0LJCqdGkiOiIyM2M5NjVjMTYwNzM3NWZlMzQ0MWFiNDFjZTZjM2JkODkzODYxNWRiIn0.qFKIpT5q4K0u1P8_jwUsQkxxcCGu3uGsQKi33c-1gEM",
  "expires_in": 3600,                                 
  "refresh_token": "ec32176f77ebd556210912ae8891aa08ff8ec3e4"
}

Rate Limits

In order to ensure smooth operation for all our users, modest rate limits apply to to all HashItem and Receipt requests. Currently, the limits for these requests are 100 per second and 1,000 per hour. If you require higher limits, please contact us and we will find a solution for your needs.

If you exceed the API rate limits, API requests will fail with an HTTP 429: Too Many Requests response.

Requests

Tierion uses REST methodology for its APIs. All data included in requests to API methods must be JSON formatted or form-urlencoded.

Remember to set the content-type header to the format of your data.

Content-Type: application/x-www-form-urlencoded

or

Content-Type: application/json

Responses

All responses are JSON formatted.

If an error occurs when making an API request, an appropriate HTTP error status code is returned, along with a message describing the error. The following is an example of an error response.

Status: 404 Not Found
{
  "error": "Datastore with Id = 574564534 does not exist."
}

HashItems

HashItems represent the individual SHA-256 hashes to be anchored to the blockchain.

Methods

Method Description
Submit HashItem Submits a new HashItem for processing onto the blockchain.

HashItem Object

Name Description
receiptId The Id of the Receipt for this HashItem which is available after processing.
timestamp The number of seconds elapsed since epoch when this HashItem was submitted.

Submit HashItem

This method submits a new HashItem for processing onto the blockchain.

POST https://hashapi.tierion.com/v1/hashitems

Parameters

Name Description
hash The SHA-256 hash to be anchored to the blockchain. [Required]

Request Sample

POST   https://hashapi.tierion.com/v1/hashitems
{
  "hash": "9dbd72de6836ce7c05c0c065b474af43598cdaace5deae8054e8efb03cb58d81"
}

Response Sample

Status: 200 OK
{
  "receiptId": "571694dd6b5c7b711861ea67",
  "timestamp": 1461097693
}

Receipts

Receipts are the Blockchain Receipt objects produced for each HashItem submitted.

Methods

Method Description
Get Receipt Return a Receipt for a particular HashItem.

Receipt Object

Name Description
receipt The content of the Receipt.

Get Receipt

This method returns a Receipt for a particular HashItem.

GET https://hashapi.tierion.com/v1/receipts/<id>

Request Sample

GET   https://hashapi.tierion.com/v1/receipts/5717a47db1b9c45a1939f005

Response Sample

Status: 200 OK
{
  "receipt": "{\"@context\":\"https://w3id.org/chainpoint/v2\",\"type\":\"ChainpointSHA256v2\",\"targetHash\":\"a83a2c5c11a2bc814d0b1dca0a385d71a1f4d662b4e31335ba7562c56cce15b1\",\"merkleRoot\":\"2d21167d2f2f73e309d5ac00ab9faaf8b530478c5b64dcd5755511c8a3eccfa3\",\"proof\":[{\"left\":\"7c6e3b0159f1359d0f9f5a3b923011b7466bdf1423317ca09121b5dc61ad1836\"},{\"right\":\"541c5ae04e83c2880296818978511893ba1b00f1515162cd865f25da54f636d0\"},{\"right\":\"67b7ced55a4db4bb0fbaf2036901888a08ab7d8126556431258017652cf62092\"}],\"anchors\":[{\"type\":\"BTCOpReturn\",\"sourceId\":\"33884d525ca1cc54313fa2f27be4cf3442b35314866851cc7fc5ec3973d80250\"}]}"
}

BlockSubscriptions

BlockSubscriptions are callbacks that will alert you when a block of HashItems has been processed and the corresponding Receipts have been generated. A BlockSubscription Payload will be POSTed to the callbackUrl you specify. Blocks are processed at the top of the hour.

Methods

Method Description
Get All BlockSubscriptions Return a list of the BlockSubscriptions for your account.
Get BlockSubscription Return the details of a specific BlockSubscription.
Create BlockSubscription Configure a new BlockSubscription callback to your HTTP endpoint.
Update BlockSubscription Update an existing BlockSubscription callback's settings.
Delete BlockSubscription Delete a BlockSubscription.

BlockSubscription Object

Name Description
id A unique identifier for the BlockSubscription within the system.
callbackUrl The HTTP endpoint that receives the callback payload.
label An optional label for this BlockSubscription.

BlockSubscription Payload Object

Name Description
id A unique identifier for the HashItem block within the system.
merkleRoot The root value in the receipts that is anchored to the blockchain.
transactionId The bitcoin transaction Id of the transaction containing the merkleRoot value.
startTimestamp The starting epoch timestamp for the set of HastItems processed in this block, inclusive.
endTimestamp The ending epoch timestamp for the set of HastItems processed in this block, exclusive.

The BlockSubscription Payload will be of type application/x-www-form-urlencoded

BlockSubscription Callback Authentication

Every BlockSubscription callback will include an 'x-tierion-sig' header containing the HMAC-SHA256 signature of the request. You can calculate the HMAC yourself and compare it with the value provided to ensure that the callback originates from Tierion and is valid. In order to calculate the HMAC, you must use the raw body of the POST request and your account's Client Secret. You will find your Client Secret value under the API tab within the main Tierion application.

The HMAC-SHA256 signature is generated using UTF8 encoding

Get All BlockSubscriptions

This method will return a list of the BlockSubscriptions for your account.

GET  https://hashapi.tierion.com/v1/blocksubscriptions

Request Sample

GET   https://hashapi.tierion.com/v1/blocksubscriptions

Response Sample

Status: 200 OK
[
  {
    "id": "570fd5940d8642f55a76c26c",
    "callbackUrl": "https://www.myserver.com/tierioncallback"
  }, 
  {                                 
    "id": "57a507b0b69073170ef4747e",
    "callbackUrl": "https://www.testserver.com/tierioncallback",
    "label": "TestServer"
  }, 
  {                                 
    "id": "57a50c60e33bf510bfc6862f",
    "callbackUrl": "https://www.devserver.com/tierioncallback",
    "label": "DevServer"
  }
]

Get BlockSubscription

This method will return the details of a specific BlockSubscription.

GET  https://hashapi.tierion.com/v1/blocksubscriptions/<id>

Request Sample

GET   https://hashapi.tierion.com/v1/blocksubscriptions/570fd5940d8642f55a76c26c

Response Sample

Status: 200 OK
{
  "callbackUrl": "https://www.myserver.com/tierioncallback"
}

Create BlockSubscription

This method will configure a new BlockSubscription callback to your HTTP endpoint.

POST https://hashapi.tierion.com/v1/blocksubscriptions

Parameters

Name Description
callbackUrl A valid HTTP endpoint to receive the callback payload. [Required]
label Label to describe this BlockSubscription. [Optional]

Creating BlockSubscriptions with duplicate callbackUrls is not permitted.

Request Sample

POST   https://hashapi.tierion.com/v1/blocksubscriptions
{                                 
  "callbackUrl": "http://www.myserver.com/callbackhandler",                                 
  "label": "Production"
}

Response Sample

Status: 201 Created Location: https://hashapi.tierion.com/v1/blocksubscriptions/5717ccd46b5c7b711861ea6c
{
  "id": "5717ccd46b5c7b711861ea6c"
}

Update BlockSubscription

This method will update an existing BlockSubscription callback's settings.

PUT https://hashapi.tierion.com/v1/blocksubscriptions/<id>

Parameters

Name Description
callbackUrl A valid HTTP endpoint to receive the callback payload. [Optional]
label Label to describe this BlockSubscription. [Optional]

Request Sample

PUT   https://hashapi.tierion.com/v1/blocksubscriptions/5717ccd46b5c7b711861ea6c
{
  "callbackUrl": "http://www.otherserver.com/handler"
}

Response Sample

Status: 200 OK
{                                 
  "callbackUrl": "http://www.otherserver.com/handler",                                 
  "label": "Production"
}

Delete BlockSubscription

This method will delete a BlockSubscriptions.

DELETE https://hashapi.tierion.com/v1/blocksubscriptions/<id>

Request Sample

DELETE   https://hashapi.tierion.com/v1/blocksubscriptions/5717ccd46b5c7b711861ea6c

Response Sample

Status: 200 OK
{                                 
  "callbackUrl": "http://www.otherserver.com/handler",                                 
  "label": "Production"
}