Getting Started
Prerequisites
You must have an account and acquire your credentials (API keys) before accessing the Truvera API. You can register an account and generate a key in your Truvera Workspace dashboard.
Keep in mind that your API keys should be kept private, so keep them safe! Do not post your private API keys on GitHub, in client-side code, or anywhere else that is publicly available.
Endpoints
Truvera provides two endpoints based on which mode was selected when creating your API key. By default trial users only have access to Test data. Paid subscribers can create to production API keys by switching the test mode toggle in Truvera Workspace in the top right next to your avatar icon. Once in test mode you will see only testnet transactions, API keys, webhooks etc.
It should be noted that in test mode your used transaction count will not increase or hit monthly limits allowing for sandboxing on our test network.
For production mode, use the endpoint: https://api.truvera.io
For test mode, use the endpoint: https://api-testnet.truvera.io
Any transaction you perform in test mode cannot be used for production. This means that, for example, any DID created in test mode will not work for issuing or verification in production.
test mode will be subject to data resets periodically, so the DIDs, etc. that you create there should not be expected to be permanent.
Authentication
Truvera uses API keys to authenticate requests. You can obtain an API Key by signing into Truvera Workspace. Once a key has been generated, it should be included in all request headers as below:
API Key (accessToken)
Name: TRUVERA-API-TOKEN
OR HTTP Bearer Authorization
When you generate an API key, you may include a list of whitelisted IP's that can use with that key.
Architecture Style
Truvera is built using a REST architecture. Our API uses standard HTTP response codes, authentication, delivers JSON-encoded responses, accepts form-encoded request bodies, and accepts form-encoded request bodies.
HTTPS is required for all API requests. Requests performed via plain HTTP will be rejected. API requests that do not include authentication will also fail. JSON requests should typically be encoded as UTF-8.
GET
Gets one or many resources
POST
Creates a new resources
PATCH
Partially updates a resource
DELETE
Deletes a resource
Rate Limits
We allow you to make up to 200 requests in a 2 minute window (avg 100 reqs/min or 1.6 reqs/second). If you exceed beyond that, you will receive a 429 Too Many Requests response and have to wait up to a minute for the next request depending on when you hit the limit. If you require higher rate limits, please contact us.
Error Handling
The Truvera API uses standard HTTP response codes to indicate if an API request was successful or unsuccessful.
The table below shows the most frequent HTTP error messages:
400
Bad Request -- Your request was rejected (e.g., missing mandatory field).
402
Payment required -- Transaction limit reached or upgrade required to proceed
401
Unauthorized -- Do not own resource or have an invalid API key in the header.
404
Not Found -- The resource that you're trying to interact with could not be found on the server.
405
Method Not Allowed -- The requested method does not exist in the API spec. Please check the {did} value and ensure that it's not empty/blank.
429
Too Many Requests -- You sent too many requests. Please try to reduce the number of requests.
500
Server Errors -- Something has gone wrong on the server. Contact us if this keeps happening.
Terminology
It is important to fully understand all the terminologies within the Truvera ecosystem. The following are common terminologies within our ecosystem:
DID
DID stands for Decentralized Identifier. It is a new type of identifier that enables verifiable, decentralized digital identity. A DID refers to any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) as determined by the controller of the DID. For more information, please refer here.
Data Schema
The structure that describes the logical view of the data. It is useful to enforce a specific structure on a collection of data like a Verifiable Credential.
Registries
A process to verify credentials in such a way that each verified credential has its own unique number. This process references a credential definition and specifies how revocation of that credential type will be handled.
Schema
The structure of credentials which are shareable among issuers as they do not contain any cryptographic material and thus are created less frequently.
Blob
Blob stands for Binary Large OBject. It is a collection of binary data stored as a single entity. The schemas are identified and retrieved by their unique blob id, which is a 32-byte long hex string.
DID Resolver
The tool that initiates the process of learning the DID document.
Last updated