Overview

An API key is a long-lived credential you create from your Truestamp account to let a program authenticate to the API without a password or a browser sign-in. You present it on every request as an HTTP bearer credential, and Truestamp treats the request as coming from your account. API keys are the simplest way to wire a script, a server, or a scheduled job into Truestamp.

A key authenticates the JSON:API REST surface, the GraphQL surface, and the console WebSocket. All three accept the same credential form. The one surface that does NOT accept an API key is the MCP server for LLM agents, which uses OAuth 2.1 instead.

You can hold more than one key at a time, each with its own expiry. You create a key, copy its value once at creation, use it until it expires or you revoke it, and every time a program authenticates with it Truestamp records the event in your account’s security activity. A key carries the full authority of your account: it is not limited to a subset of operations, so treat it like a password.

Presenting a key on a request

Every key is a single opaque string that begins with the prefix truestamp_. Send it in the standard bearer form on the JSON:API and GraphQL surfaces:

Authorization: Bearer truestamp_<...>

curl -H "Authorization: Bearer truestamp_YOUR_KEY" \
     https://www.truestamp.com/api/json/items

The same header works against GraphQL at /gql. A request with no credential, or a blank or malformed bearer value, is rejected with 401 Unauthorized and a WWW-Authenticate: Bearer challenge header, never a server error.

The console WebSocket cannot carry an Authorization header on its upgrade request, so it takes the key as an api_key connection parameter on the socket URL instead:

wss://www.truestamp.com/console/websocket?vsn=2.0.0&api_key=truestamp_YOUR_KEY

On all three surfaces the authenticated request runs as you, against your default team unless the request selects a different team. See the JSON:API HTTP surface, the GraphQL surface, and the console WebSocket for the per-surface details of tenant selection, rate limits, and available operations.

Creating a key

You create and manage keys from the API keys page in your account at /api-keys. Creating a key requires nothing but choosing how long it should live; the key value itself is generated for you.

Each key has a required expiry. When you create one you pick a duration, and the page offers a fixed set of choices: one hour, one week, one month, one year, or a long-lived key. The expiry must be in the future.

The generated key value is shown to you exactly once, at the moment of creation. Copy it then and store it somewhere safe (a secrets manager, an environment variable in your deployment). Truestamp keeps only a one-way hash of the key, never the key itself, so there is no way to reveal the value again later. If you lose it, revoke the key and create a new one. To confirm a new key works, call the whoami endpoint, GET /api/json/users/me on the JSON:API surface, which returns your own user record when the credential is valid.

You can create multiple keys and hold several active at once. This lets you issue a separate key per integration or per machine, so you can revoke one without breaking the others. Only you can create keys for your own account, and you can only see and manage your own keys.

Validity, expiry, and revocation

A key is valid while its expiry is in the future. Once the expiry passes, the key stops authenticating and any request using it is rejected with 401. Choosing a shorter expiry limits the blast radius if a key ever leaks.

You can revoke a key at any time from the API keys page. Revocation deletes the key immediately and permanently: subsequent requests with that key fail. There is no grace period and no undo, so revoke a key the moment you suspect it has been exposed. The API keys page shows each key with its expiry and whether it is still active, and updates live if you create or revoke a key in another browser tab or session.

When you delete your account, all of your API keys are destroyed as part of the deletion, so no orphaned credential can outlive the account.

What a key can and cannot do

An API key authenticates as your whole account. It is not scoped or restricted to a subset of operations, so any request it makes can do anything you are allowed to do through the API. This is the key difference from an OAuth 2.1 access token, which carries explicit per-surface scopes (for example a read-only or write scope) that narrow what the token may do. Because an API key has no such limit, it is best suited to trusted server-side integrations you control, not to code you hand to a third party.

Account-management operations are deliberately out of reach for any API credential. Creating, altering, or deleting accounts and changing credentials (including creating or revoking API keys themselves) are not exposed on the JSON:API, GraphQL, or MCP surfaces at all; they happen only in the web app. So a leaked API key cannot be used to escalate by minting more keys or taking over the account through the API. It can, however, read and write your items and other data, which is why it must be protected like a password.

Audit trail

Every time a program authenticates with one of your API keys, Truestamp records a security-activity event on your account. You can review these events in your account’s security activity, where an “API key usage” filter shows only key authentications, separate from interactive sign-ins. Each event is timestamped and carries a truncated form of the client IP address (the last part is dropped for privacy), so you can spot key use you do not recognize. If you see activity you cannot account for, revoke the key.

API keys versus OAuth 2.1

Truestamp accepts two kinds of bearer credential, and they suit different callers.

• API key. A long-lived credential you create for your own account and hold as a secret. It authenticates JSON:API, GraphQL, and the console WebSocket. It is not scope-limited: it acts as your whole account. Best for your own trusted server-side code, scripts, and jobs.
• OAuth 2.1 access token. A short-lived, user-consented, per-surface-scoped token a client obtains through an authorization flow, with a refresh token for renewal. It authenticates the same three surfaces AND the MCP server (which accepts OAuth only). Best for a CLI, an agent connector, or any client that should get delegated, scoped, revocable access without holding a long-lived secret.

If you are wiring up your own backend, an API key is usually the least friction. If you are connecting an LLM agent or a third-party client, OAuth 2.1 is the right mechanism instead. See authentication for how you sign in to the web app itself.

Limitations

• An API key is not scoped. It carries the full authority of your account over the API, so it must be stored and rotated like a password. If you need scoped or revocable delegated access, use OAuth 2.1 instead.
• The key value is shown only once, at creation. It cannot be retrieved again; a lost key must be revoked and replaced.
• API keys do not authenticate the MCP server, which is OAuth-only.
• Revocation is immediate and permanent. There is no way to un-revoke a key or to temporarily suspend one; create a new key instead.
• API keys cannot perform account-management operations (creating accounts, changing credentials, or managing keys), which live only in the web app.