API keys

Two kinds of API key: Full access for your servers, and Decisions only for devices and services that only decide. What each may call, and why every device gets a key of its own.

Every call carries a key, and the key's kind decides what the call may do. Choose the narrowest kind that does the job: a key on a device or in a web page can be copied, and a copied key does whatever its kind allows until you revoke it.

The two kinds
Kind	`scope`	May call	Where it belongs
Full access	`full`	Everything the workspace may: decisions, models, uploads, sessions, and collections	Your servers, in a secret manager or an environment variable
Decisions only	`decide`	`POST /v1/decide` and `GET /v1/models`; a face search only where the key allows it	One per device, app install or service that only decides

Keys are made in the console under API keys, by an Owner, Admin or Developer: choose Full access (the default) or Decisions only under What this key can do. A key with no kind chosen is Full access.

Which kind to use#

Which kind to use
Where the call comes from	Use
A service of yours that does more than decide (sessions, collections)	Full access, kept on the server
A service of yours that only decides	Decisions only: the same answers, and much less to lose if it leaks
A fleet of devices: cameras, kiosks, robots, vehicles	One Decisions-only key per device, named after it, with its own rate limits
A web page with your own server behind it	Your server calls DecisionNode with its key; the page calls your server

Why every device gets its own key#

A device can be lost, opened or copied. Its key is only as safe as its storage. With a key per device, one lost device is one revoked key, and every other device keeps working.
Never a Full access key on a device or in a browser. A full key reads, changes and deletes your collections, starts sessions, and spends at the workspace's rate. Copied from one device, it is all of that for whoever has it.
Bound what a key can do. A Decisions-only key only decides, and carries its own rate limits, so a copied key can neither touch your collections nor spend at the workspace's rate.
Images go inline. A Decisions-only key cannot make uploads (POST /v1/uploads is 403 key_scope_denied), so a device sends its pictures inline or by url in the decision, up to 25 MiB a request.

A key's settings#

Face search is opt-in. A Decisions-only key cannot use the face_recognition booster unless you tick May search your face collections when you create it or edit it (may_search_collections). Anyone holding such a key can search your collections and read the matches, so tick it only for a device that runs face recognition. A Full access key always may.
Its own rate limits. Under Rate limits (optional), set the key's own Requests per second and Tokens per second, each a whole number from 1 to your workspace's own. Left empty, the workspace's limit applies. Over them, 429 rate_limit_error with Retry-After, as for any key.

What a key's kind refuses#

A call outside a key's kind is 403 key_scope_denied, before anything runs or is billed: "This key may only make decisions." for a route the kind does not reach, such as an upload, a session or a collection, and "This key may not search collections." for a face_recognition booster on a key without the search allowed.

The 403

{
  "detail": {
    "error_type": "key_scope_denied",
    "message": "This key may only make decisions."
  }
}

A key's kind never changes#

A key's kind is set when it is made. Its name, its rate limits and the face search flag can be changed later; its kind cannot: "A key's scope is set when it is created. To change it, create a new key and revoke this one."