API keys and sessions¶

Two different things call this service. A program sends an API key; a person signs in to the dashboard and gets a session. They are not two spellings of one mechanism, and the boundary between them is deliberate.

Within the first of the two there are three kinds of key, and the differences between those are what most of this page is about.

Why keys and sessions are separate¶

An API key identifies a program. It is a long-lived bearer credential, configured once into a deployment. It may recognize documents and read that account's own results.

A session identifies a person at a browser. It is short-lived and bound to a sign-in. The dashboard uses it to manage the account: issuing and revoking keys, choosing a retention window, taking a top-up quote.

The two sets of powers do not overlap, and that is the point. A key that could issue keys would turn one leaked credential into an account nobody can take back. The attacker mints a second key before the first is revoked. Keeping key management behind a sign-in means that recovering from a leaked key is always possible, using something the leak did not contain.

It works in the other direction too. A browser session is exposed to a class of risk a server-side key is not. It is therefore not the credential that spends money on recognition at scale.

The account-management routes are therefore outside the versioned API surface and are not part of the published contract. They are the dashboard's, and the dashboard is their client.

What a key is made of¶

A key looks like sk_live_9c41ba2e…: a kind marker, then a body of random characters carrying 128 bits of entropy.

The kind is in the prefix rather than looked up anywhere. A credential beginning sk_sandbox_ is never charged, and that is decided by reading those characters. It cannot drift from a row in a table, because there is no row in a table saying otherwise.

Only a hash of the key is stored. The service can tell whether a presented key is one it issued, and it cannot produce the key itself. A key is therefore shown in full exactly once, at creation. Afterwards it is known by its prefix: the marker plus the first 8 characters of the body. That is enough to recognize a key in a list and not enough to use it.

A key can be given an end of validity, and a key past it is refused like an unknown one. A revoked key is refused the same way. A caller cannot tell an unknown key from a withdrawn one, which is the answer that reveals least.

The public sandbox key¶

sk_sandbox_public is printed in this documentation, on the home page and in every runnable example. Publishing a credential sounds like a mistake, and here it is the design.

It belongs to no account. It has no balance to spend, no history to read and no settings to change. GET /v1/usage answers it with a null balance and zero counters rather than somebody's figures, and it reads no stored scan.

What it can do is recognize. A document sent on the public key reaches the real engine and comes back really read. The alternative is a fixed answer for every image, which makes a product look broken to the person trying it on their own passport.

Three walls bound that, and all three are keyed to the client rather than to the key. Everybody shares the credential, so counting per key would count the world as one caller. The rate bucket is per address. The lifetime free allowance is per client. And the same image resubmitted past a small threshold is refused, so one picture cannot be replayed to consume the demo.

Those walls fail closed. When the store holding the counters cannot be reached, the anonymous path answers a retryable 503 rather than letting unmetered free recognition through. A registered key is unaffected; it is metered by its own balance.

Because the key is published, the recognitions it produces are never stored. No account exists for them to belong to.

An account's own sandbox key¶

The second kind is a sandbox key an account issues for itself, and it does something different from the public one.

It is answered from a fixed synthetic specimen and never reaches the Engine at all. Every call returns the same invented holder, the same document, the same zone. Nothing about the image that was sent affects the answer beyond being validated and counted.

That is what makes it the integration credential. A client built against it can assert on exact values in a test, because the values do not move. It spends no recognition capacity and is never charged. No real identity document is read on the credential an account is most likely to hand around.

It reads no stored scan either. GET /v1/scans/{id} answers 404 for every sandbox key, including the account's own results. An account's history is a store of identity data, and this is the low-trust key.

Its usage figures, on the other hand, are the account's real ones. Usage is an account-level question, and the answer does not change with the key that asked it.

The live key¶

The third kind is the one that does the work. It reaches the engine and draws credits. Its results are stored under the account's retention window, and it is the only kind that can read them back.

Everything a live key can do is a reason to treat it as a secret. It spends money, and it opens a history of identity documents. An account may hold several, which is what makes it possible to replace one without a gap. Rotate API keys is that procedure.

Why the three exist rather than one¶

A single key with a test-mode flag is the obvious alternative. It fails at the first question a developer asks: how do I try this before I sign up.

The three kinds answer three different moments. The public key is for the minute before an account exists, where the only thing that matters is that a real document reads correctly. The account's sandbox key is for the weeks of building against a stable answer. The live key is for production.

Each of them is bounded by what its moment justifies. The public key recognizes for real and is walled by client. The sandbox key is free and reads nothing. The live key does everything and is the one worth protecting. A caller who knows which of the three is in a deployment can predict the whole of its behavior. That is what a credential ought to make possible.