UNAUTHORIZED - Devotel Orbit Documentation

What this error means

UNAUTHORIZED is returned with HTTP status 401 when the request does not carry a valid credential: no API key or session at all, a key that has been revoked, a key used against the wrong mode (live versus test), or a malformed bearer token. The request is rejected before any work is done. Every response for this error carries this page’s address in meta.docs_url:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Provide X-API-Key or sign in via Clerk.",
    "status": 401
  },
  "meta": {
    "request_id": "req_01J9ZKQ3V8",
    "docs_url": "https://docs.orbit.devotel.io/errors/UNAUTHORIZED"
  }
}

Cause

State	Why it returns 401
No credential sent	Neither `X-API-Key` nor a signed-in session is present
Test key against the live host, or live key against test	A key is only valid in the mode it was minted for
Revoked key	The key was deleted under Settings → API Keys, or revoked when a SCIM-deprovisioned member left the organization
Truncated or malformed bearer token	A copy-paste or stale token that cannot be decoded
Key from a different organization	Keys are tenant-bound and do not work cross-organization

How to fix it

Send the key in X-API-Key from your backend. Secret keys (dv_..._sk_) belong in server-side code only; a key shipped to a browser should be treated as publicly visible.
Check live versus test. Confirm the key’s mode matches the host and mode you are sending against; a perfectly valid key in the wrong mode is indistinguishable from a bad one.
Re-mint revoked keys. If the key was deleted, or a SCIM deprovisioning cascade revoked a departed member’s keys, create a new key under Settings → API Keys. Note that SCIM-provisioned members are not blocked from the API while active: they can mint and use keys like any member, and revocation happens at deprovisioning, not at provisioning.
Replace hand-built Authorization headers. If you pass a bearer token, regenerate it rather than patching a truncated one.

A 401 is never transient: retrying the same credential produces the same rejection.

Error Code Reference — the UNAUTHORIZED row with its status and cause.
Auth and API keys runbook — key lifecycle, modes, and revocation.
Error Handling Examples — response-envelope handling patterns in code.

​What this error means

​Cause

​How to fix it

​Related

What this error means

Cause

How to fix it

Related