Authentication

One Bearer token on every request. This page covers where to get it, what it is, and what each failure actually means.

Every endpoint under api.buildonto.dev/v1/* reads the same header. There is no other auth scheme — no query parameter, no cookie, no signature.

curl https://api.buildonto.dev/v1/usage \
  -H "Authorization: Bearer onto_sk_live_YOUR_KEY"

GET /v1/usage is the cheapest way to check a key works: it costs no credits, takes no concurrency slot, and returns your plan, monthly limit and remaining balance.

A key is a fixed prefix and 24 random bytes, base64url-encoded. Nothing is encoded in it — it is an opaque lookup value, not a signed token, so it carries no account id, no scope and no expiry.

onto_sk_live_  +  32 random characters   =  45 characters
└───────────┘     └──────────────────┘
 13 chars          base64url of 24 bytes

The first 12 characters are stored alongside the digest. That is
"onto_sk_live" for every key, so it does not tell keys apart.
Never log anything after it.

Authentication checks the key's status on every request, so revocation takes effect on the very next call rather than at the end of a cache window. There is no propagation delay to wait out.

An account has one active key. Creating a key revokes every active key first, so the old key stops working the moment the new one exists. Revoked keys are not listed and cannot be reactivated.

Every auth failure returns the same status and code, deliberately: the API does not distinguish a malformed key from a revoked one from a key that never existed, because that difference is only useful to someone guessing.

Onto issues three kinds of credential. A per-site key sent to /v1/* is a 401 that looks like a broken key.

The connector token is a signed JWT and always starts eyJ. API keys are opaque and always start onto_. The API accepts both as a Bearer token on /v1/*, and both bill the same account. A connector token expires about 2 minutes after it is minted.