> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UNAUTHORIZED

> The request carried no valid credential, so it was rejected with HTTP 401.

## 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`:

```json theme={null}
{
  "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

1. **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.
2. **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.
3. **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.
4. **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.

## Related

* [Error Code Reference](https://docs.orbit.devotel.io/reference/error-codes.md#from-a-code-to-a-runbook) — the
  `UNAUTHORIZED` row with its status and cause.
* [Auth and API keys runbook](https://docs.orbit.devotel.io/troubleshooting/auth-and-api-keys.md) — key
  lifecycle, modes, and revocation.
* [Error Handling Examples](https://docs.orbit.devotel.io/guides/error-handling-examples.md) — response-envelope
  handling patterns in code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.