API keys

A key looks like this:

tsk_live_9fq3mNbx_r7Kd2xPmQvTb4nHy8sZaJcW3eLuGfDkR

Two parts after the prefix: a reference that identifies which key row this is, and a secret. Only the reference and the last four characters of the secret are stored in readable form — the token itself is kept as an argon2id hash. Nobody can read your key back to you, including us. If you lose it, ask us to revoke it and issue another.

Send it as a bearer token:

Authorization: Bearer tsk_live_9fq3mNbx_r7Kd2xPmQvTb4nHy8sZaJcW3eLuGfDkR

One key per agent

Every request we record carries the key that made it, and spend is broken down by key. That is the only attribution you get: the OpenAI fields people usually reach for — user, metadata — are ignored here, so nothing else in a request identifies who sent it.

So the key name is the attribution. Name keys after the thing that holds them:

coding-agent
docs-assistant
nightly-eval
ci

not production, key-2, or main. When one line of your bill triples, the name is what tells you which agent did it.

Three more things fall out of this, all of them practical:

• Rate limits are per key, not per account. 600 requests and 2,000,000 tokens per minute, and 64 concurrent requests, each apply to one key. A runaway agent throttles itself instead of taking down everything else you run.
• Revocation is per key. A leaked key on one machine is one agent to redeploy, not every agent you own.
• Blast radius is per key. A key you gave to a third-party tool cannot see what the rest of your keys are doing.

Keys are cheap. Make more of them than feels necessary.

Revocation

Revocation is not self-serve either: ask us and we revoke the key. It takes effect in the ledger immediately, but a verified key is cached for performance, so a revoked key may keep working for up to five minutes.

If a key has genuinely leaked, revoke it and then treat the next five minutes as exposed: watch the spend, and top up no further credit until the window has passed. A zero balance stops a leaked key instantly, which revocation alone does not.

In the other direction, a token that was rejected is remembered as invalid for about a minute, so a key that failed once will keep failing briefly even after the underlying problem is fixed.

Keys and the console are separate

An API key authenticates https://api.shardio.ai/v1 and nothing else. It cannot read your usage, list your keys, or buy credits — the console API refuses it outright. In the other direction, a signed-in console session cannot call /v1.

That separation is not incidental. It is what makes handing a key to an agent, a CI job or a third-party tool a bounded decision: the worst it can do is spend credits.