Skip to main content
Every headless call into Tessary carries a project API key in an Authorization: Bearer header. A key belongs to exactly one project, carries exactly one scope, and acts with the role member no matter who minted it. There is one key store behind all of them. The keys on Settings → API keys and the tokens on Settings → MCP tokens are rows in the same table, issued and verified by the same service, and differ only in the scope they carry.

​
The three scopes

Admin is the superset family. Write and query are strictly least privilege: the query API refuses a write key, and ingest refuses a query key. Only an admin key satisfies /mcp, and it satisfies the other two surfaces as well, so a single tsy_a_ key works when an application wants one credential instead of three.
The scope letter in the prefix is a readability aid so a write-only key is recognizable at a glance. The stored scope column is what the server enforces.

​
Where keys are minted

1

Open the project you want the key scoped to

A key binds to one project at issue time. Ingest, the query API, and /mcp take no project argument at all: they resolve the project from the token. A key cannot be moved between projects.
2

Mint a key on Settings → API keys

This page issues all three scopes. Select New key, enter a name, choose Write, Query, or Admin, then select Create key.
The new key appears in the list with its scope badge and its prefix, shown as tsy_w_....
3

Or issue an admin token on Settings → MCP tokens

This page issues admin-scoped tokens only, for wiring an MCP (Model Context Protocol) client such as Claude Code to one project. Select New token, name it, then select Issue token.
The token appears in the list with its prefix and a Last used column reading Never.
4

Copy the secret before you close the dialog

Tessary stores a bcrypt hash and the lookup prefix, never the secret. Tessary shows the plaintext exactly once, at creation or rotation. Losing it means rotating the key for a fresh secret; there is no recovery.
Both pages sit under Security & access in project settings, alongside PII redaction and Data retention. Two other surfaces mint a write-scoped ingest key for you. The connect gate you land on after sign-up mints a key named OTLP ingest as the screen loads, with no control to press, and shows it in its Bearer Token field; reloading that screen mints another. Settings → Sources offers the same key behind a Create a connection token button and then shows it as a ready-made Authorization: Bearer value in its Header field. Set up Tessary covers the connect gate.

​
How a key is presented on the wire

Send the key as a bearer credential. Nothing else authenticates these surfaces: /mcp ignores cookies entirely, and on /api/** Tessary prefers a cookie session and falls back to the bearer header for headless callers.
An OpenTelemetry SDK or Collector reads the same header from its standard environment variable:
The traces-suffixed variables are the ones the connect screen hands you, and the ones to use. The unsuffixed pair also redirects metrics and logs, which Tessary does not accept. Over OTLP gRPC the same value goes in the authorization request metadata entry, which is the gRPC spelling of the header. For the MCP client configuration block, see MCP server.

​
Token format

A token is the 6-character literal prefix plus 22 URL-safe base64 characters generated from 16 random bytes:
The 8 random characters inside the lookup prefix are what stop an attacker grinding a small alphabet to find live prefixes and then confirming hits through verification timing. Verification is cached for a short interval so bcrypt stays off the per-request path. Revocation does not wait for that cache to expire: every revocation path evicts the key in the same call that writes the revocation.

​
Constraints

  • A key belongs to one project. Deleting the project revokes its whole key set immediately.
  • A key acts as role member, whoever minted it. It cannot carry more than a member’s permissions.
  • A key cannot mint another key. Tessary refuses a create-key or issue-token request that is itself authenticated with a bearer key.
  • scope is required when creating a key, and must be one of write, query, or admin.
  • Listing keys requires the ORG_VIEW permission. Creating, rotating, and revoking require ORG_MANAGE, so a viewer cannot mint a billable ingest or query key.
  • Rotation keeps the name and the scope and issues a new secret. The old secret stops verifying immediately, so update every client that uses it.
  • Revocation is immediate and cannot be undone.
  • A revoked key cannot be rotated.
  • Every create, rotate, and revoke writes an audit row. Read the trail under Audit on Settings → API keys, or at GET /api/orgs/{orgSlug}/projects/{projectSlug}/api-keys/audit.
  • A key whose project no longer exists fails verification rather than resolving to an empty context.

​
Errors

Each surface answers a missing or wrongly scoped credential in its own idiom. All of them refuse before any work runs. The ingest error message says “mcp key” where the wire value is admin. Both name the same family.
Treat a leaked write key as an open door onto the project’s trace data and a leaked admin key as an open door onto everything the MCP tools read. Revoke it from Settings → API keys rather than rotating it if you no longer want that client to have a key at all: rotation issues a replacement, revocation does not.

MCP server

The endpoint an admin key unlocks, its complete tool list, and client configuration.

Ingestion contract

Every field the platform consumes from a span a write key pushes.

Set up Tessary

First boot, the connect gate, and the first write key it mints for you.

Configuration reference

The environment variables behind ingest transports, sealing keys, and retention.