UNAUTHORIZED

The Bearer token is missing, malformed, or has been revoked.

What this means

UNAUTHORIZED fires when the `Authorization` header is missing entirely, isn't formatted as `Bearer <token>`, or the token doesn't match any active API key in the Onto database. Revoking a key from the dashboard takes effect immediately — in-flight requests using a revoked key will start receiving 401s on the next round-trip.

When you'll see it

HTTP 401. Body always includes code: "UNAUTHORIZED". Branch on code, never on the human-readable message — wording can change without notice; the code is the stable contract.

Example response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or revoked API key"
}

How to handle

Re-issue a key from app.buildonto.dev/read/keys. Each user can have multiple active keys, so rotate one at a time to avoid downtime. Treat the key like any other secret: don't commit it, don't log it, prefer an environment variable. If your application is multi-tenant, scope keys per workspace so revocation is surgical.

Suggested handling in a Node client:

if (data.code === 'UNAUTHORIZED') {
  // Your key got revoked or expired — page ops, do not retry blindly.
  notifyOps('Onto API key is invalid; rotate from dashboard');
  throw new Error('Onto: UNAUTHORIZED — refresh your key');
}

Related errors

See the full error index for the complete catalog with the handling switch statement covering every code at once.