# Getting started ## Architecture style Truvera is built using a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) architecture. Our API follows common patterns including standard HTTP header authentication and standard HTTP response codes. It accepts form-encoded request bodies and delivers JSON-encoded responses. 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. ## Terminology Understanding key terminology in Truvera will help you to use the API:
TerminologyDescription
DIDDecentralized Identifiers (DIDs) are identifiers that enable 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 to the W3C standard or Credential SDK docs.
Verifiable CredentialA verifiable credential is a specific way to express a set of claims made by an issuer so that it is tamper-resistant and can be delivered to a verifier via a wallet in control of the data subject. For more information, pleases refer to the W3C standard.
Data SchemaThe 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.
SchemaThe list of attributes and structure of a credential that is used to create a verifiable credential of a specific type. It does not contain any cryptographic material and is shareable among issuers.
RegistriesA reference to a unique credential in context of a process for handling revocation of that credential type.
BlobBlob 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 ResolverThe tool that initiates the process of learning the DID document.
## Asynchronous responses When possible, calling the API will immediately return the desired result in a synchronous response. When the result of an operation may be delayed, an asynchronous pattern is used to close the connection and avoid blocking system resources. Calls that are asynchronous due to an interaction with another party ([such as requesting a proof presentation from a credential holder](https://docs.truvera.io/truvera-api/presentations/proof-requests)) will return a resource identifier that will be updated as the resource is processed through its workflow. Calls that are asynchronous due to a dependency on an external system (such as a blockchain) will trigger [a job to be queued](https://docs.truvera.io/truvera-api/jobs). These operations will provide an immediate response to indicate whether a request was accepted for processing, but the result must be obtained asynchronously using one of the methods below. For ease of integration, we recommend getting your flow to work using polling and then switching to webhooks as you prepare for production usage. ### Asynchronous polling A call may create a resource with a unique identifier, which can then be checked for updates. System resources can be unblocked by polling for the response in a background thread. Polling can also be done by a proxy behind a white-labeled API. ### Asynchronous webhook responses [By registering a webhook](https://docs.truvera.io/truvera-api/webhooks), Truvera can asynchronously provide your integration with data when it is available—thereby reducing the load of repeated polling. The webhook response will confirm that an event occurred and provide you with key information about the event. If additional details are needed, the webhook response contains a resource identifier that you can use to call back the same API you would use for polling. ## 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](https://truvera.io/keys) dashboard. {% hint style="warning" %} 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. {% endhint %} We generally recommend configuring your solution in the [Truvera Workspace](https://docs.truvera.io/truvera-workspace), as it provides an easy to use interface for managing organization profiles, creating schemas, setting up verification templates, and administering ecosystems. You can even manually issue and verify through the web interface. When creating schemas and verification templates, you can download JSON that can then be used to complete the same action via the API. We also recommend using the [Truvera Wallet](https://docs.truvera.io/credential-wallet/truvera-mobile-wallet) to hold and present your credentials while you are testing the API. Once you have your basic flow working, you can then customize the holder's wallet experience using the [Truvera Wallet SDK](https://docs.truvera.io/credential-wallet/wallet-sdk). ## 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 production API keys by switching the **test mode** toggle in Truvera Workspace in the top right next to your avatar icon. When 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: * For test mode, use the endpoint: {% hint style="warning" %} 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**. {% endhint %} {% hint style="warning" %} **Test mode** will be subject to data resets periodically, so the DIDs, etc. that you create there should not be expected to be permanent. {% endhint %} ## Authentication Truvera uses API keys to authenticate requests. You can obtain an API key by signing into [Truvera Workspace](https://truvera.io/). Once a key has been generated, it should be included in **all** request using dual-header authentication as below: ``` DOCK-API-TOKEN: Authorization: Bearer ``` When you generate an API key, you may include a list of whitelisted IP's that can use with that key. ## 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](https://docs.truvera.io/support). ## 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:
CodeMeaning
400Bad Request — Your request was rejected (e.g., missing mandatory field).
402Payment required — Transaction limit reached or upgrade required to proceed
401Unauthorized — Do not own resource or have an invalid API key in the header.
404Not Found — The resource that you're trying to interact with could not be found on the server.
405Method 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.
429Too Many Requests — You sent too many requests. Please try to reduce the number of requests.
500Server Errors — Something has gone wrong on the server. Contact us if this keeps happening.
## Development Tips The Truvera Workspace is built using the REST API, so the network request viewer in your browser's developer tools will show the JSON used in requests and responses which you can then copy to your API calls. You can also examine errors in the browser developer console to get more insight into what is happening. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.truvera.io/truvera-api/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.