Skip to main content

API | Intro

This page will help you get started using the Truestamp API. You'll be up and running in no time!

Truestamp provides an HTTP REST API that can be accessed using any HTTP client, the Truestamp CLI, or one of the Software Development Kits (SDK) we provide. Our goal is to make life easy for you as a developer, whether you choose to use simple tools like curl or HTTPie, or even if you want to build your own SDK library.

New to Truestamp?

If you are just getting started with Truestamp, be sure to visit our Learn section where you can read about the fundamentals of how Truestamp works.

Prerequisites

Truestamp exposes a standard HTTP REST API so you'll only need a few things to get started:

  • an HTTPS client
  • a way to create a cryptographic hash like SHA-256

These are part of the standard library for just about every programming language and operating system. We do provide some tools to simplify interacting with the API that you can explore elsewhere in this documentation.

Platform

Here you'll find the information you'll need to get started accessing the Truestamp API.

Scheme

All connections to the API must be performed using encrypted TLS (https).

Base URI

The base URI endpoint for all API connections is:

https://api.truestamp.com

Versioning

There is currently a single Version 1 (v1) version of the API. This should be appended to the Base URI.

https://api.truestamp.com/v1

Resources

The RESTful resource you are accessing must be appended to the Base URI + Version.

https://api.truestamp.com/v1/[RESOURCE]

Methods

The standard HTTP methods are supported.

  • GET
  • POST
  • PUT
  • DELETE

CORS

All API endpoints provide the appropriate CORS headers to allow cross-origin requests from browser clients.

Requests

Authentication/Authorization Headers

All requests to the API must be accompanied by a valid Bearer access token. This access token can take take the form of a JSON Web Token (JWT) or API Key.

JWT tokens are typically provided once you login via the Truestamp website or CLI via an interactive OpenIDConnect/Oauth2 flow. Typically you won't need to handle these directly as they are provided by our identity provider and used behind the scenes.

For those clients where it is not possible to participate in interactive user-oriented authentication flows, we make it possible to generate user-scoped long lived API Keys. These keys can be presented in the Authorization header in place of a JWT token. The long lived tokens have a configurable expiration time, and can be revoked in case of abuse or security breach.

How do I get an API Key?

The easiest way to issue such a key is by using the keys sub-command of the Truestamp CLI or by using the tool provided in the web application Dashboard.

The expected form of the Authorization header is like the folllowing, where [API_KEY] is your JWT or API Key value:

Authorization: Bearer API_KEY

There MUST be a space between Bearer and the access token value. The access token value should not be wrapped in quotes per RFC 6750.

Any request to a protected endpoint that is not accompanied by a valid access token or API Key will be rejected with a 401 Unauthorized error.

Using a token with the interactive reference documentation

If you generate an API key you can paste it into the interactive API Reference Documentation to allow you to play with the API right from within the reference documentation. Just fill click on the Try It button in the docs and enter your API key when prompted.

Accept Header

All API requests should be accompanied by an Accept header that specifies */* or application/json

Content-Type Header

All POST or PUT requests that submit body content must also provide a Content-Type header that specifies application/json.

Body Content

The body, for those requests that require one such as POST or PUT methods, must be a JSON object with the appropriate shape as documented for each resource in the API reference documentation.

Responses

Status Codes

Appropriate HTTP status codes will be returned with each response. 2xx, 3xx, 4xx, and 5xx level HTTP response codes will be used.

Content-Type Header

The Content-Type response header will always contain application/json unless no body is returned.

JSON Body

If a response body is returned as application/json it will be pretty printed with newlines and two spaces for each level of indentation. The slight increase in size for pretty printing is overruled by the developer friendly nature of the more easily human readable responses.

Error responses will also be returned with a JSON body as appropriate. JSON error bodies will be served as a JSON Object with at least a message property that provides a human readable message.