Authentication

Bearer keys, the scopes they carry, and what no key can do.

Getting a key

Keys are created in the workspace, under Developers. The plaintext is shown once, at creation, and is not recoverable afterwards — store it before you close the dialog. Creating, rotating and revoking a key each write an audit row, readable through the audit endpoint below. A request with no key, or with a key TAVONEL did not issue, is refused with 401 and the code AUTH_REQUIRED: that is the first error most integrations see, and it means the credential rather than the request.

Sending the key

Send the key as a bearer token. Keys are workspace-scoped and carry an explicit scope set; a request outside its scopes is refused with 403 and API_SCOPE_REQUIRED rather than silently returning less.

curl -sS https://tavonel.com/api/v1/documents -H "Authorization: Bearer $TAVONEL_API_KEY"

The scopes a key can hold

How often you may call

Every scoped request consumes one unit of a per-minute allowance held per key and per scope. The window is a clock minute rather than a rolling one, so an allowance that is spent is free again at the top of the next minute. The per-scope numbers are on the Billing and limits page, printed from the same values the authorizer enforces.

Note Over the allowance the answer is 429 with API_RATE_LIMITED. No Retry-After header is sent on that code today and no X-RateLimit-* headers are published — waiting for the next clock minute is sufficient by construction, and documenting a header we do not send would be worse than documenting the window. The separate hourly allowance on World activation, rollback and retrieval-index rebuild answers ACTIVATION_RATE_LIMITED and does carry Retry-After.

Rotating a key, and reading the audit trail

Rotation is atomic: a replacement key is created, the source key is revoked and an audit event is written, or none of the three happened. There is no window in which the old key is dead and no replacement exists. Both operations take a signed-in browser session — a developer API key cannot call them, which is the same boundary activation sits behind.

# Browser session only. A developer API key is refused on this route.
curl -sS -X POST https://tavonel.com/api/v1/developer/keys/{id}/rotate \
  -H "Authorization: Bearer $TAVONEL_SESSION_JWT"

# Browser session only. A developer API key is refused on this route.
import os
import requests

response = requests.request(
    "POST",
    "https://tavonel.com/api/v1/developer/keys/{id}/rotate",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_SESSION_JWT"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

// Browser session only. A developer API key is refused on this route.
const response = await fetch("https://tavonel.com/api/v1/developer/keys/{id}/rotate", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TAVONEL_SESSION_JWT}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

# Browser session only. A developer API key is refused on this route.
curl -sS -X GET https://tavonel.com/api/v1/developer/audit \
  -H "Authorization: Bearer $TAVONEL_SESSION_JWT"

# Browser session only. A developer API key is refused on this route.
import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/developer/audit",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_SESSION_JWT"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

// Browser session only. A developer API key is refused on this route.
const response = await fetch("https://tavonel.com/api/v1/developer/audit", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_SESSION_JWT}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

What no key can do

Note Activation, rollback and destructive workspace actions are human-session-only. There is no scope that grants them, which is why you will not find one in this table.