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

# Bearer Token Authentication

> Authenticate with the Admin API using Authorization: Bearer tokens and strict organisation scoping.

The Admin API supports two authentication paths:

1. **`x-api-token`** — a long-lived JWT issued from **Settings → Developer → API Tokens**. Used by server-to-server scripts.
2. **`Authorization: Bearer <token>`** — short-lived user-session tokens scoped to a single organisation. Used by MCP clients, the admin panel's internal calls, and any tooling that impersonates a logged-in user.

This page covers the Bearer path. For the long-lived token path see [API Reference → Authentication](/api-reference/authentication).

<Info>
  Use Bearer tokens when the caller represents a specific **user session** (e.g. an AI agent acting on behalf of a signed-in admin). Use `x-api-token` for headless integrations.
</Info>

## How the two differ

|                    | `x-api-token`                               | `Authorization: Bearer`                                              |
| ------------------ | ------------------------------------------- | -------------------------------------------------------------------- |
| Issuer             | Admin panel → Developer settings            | Nudj auth service (NextAuth) at sign-in                              |
| Audience           | Scripts, CI, backend integrations           | Interactive user sessions, MCP clients                               |
| Lifetime           | Long-lived (rotate manually)                | Short-lived (session TTL)                                            |
| Organisation scope | Embedded in token claims                    | Enforced at the middleware by the token + `x-api-domain` combination |
| Revocation         | `POST /auth-config/tokens/{tokenId}/revoke` | Sign out or let the session expire                                   |

## Making a request

```bash theme={null}
curl -X GET "https://{subdomain}.nudj.cx/api/v2/admin/communities" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "x-api-domain: https://{subdomain}.nudj.cx/api/v2/admin"
```

Two headers, both required:

* `Authorization: Bearer <token>` — your session token.
* `x-api-domain` — the exact API domain the token is scoped to. This tells Nudj which organisation's subdomain to route the request through.

The server validates the token signature, verifies the requested org matches the token's claims, and rejects with `403` if they diverge.

## Organisation scoping (why this matters)

Before bearer-token org scoping shipped, a session minted for org A could — under specific routing conditions — be used against org B's API if the caller changed the subdomain. That cross-tenant leak is closed: every Bearer request is checked at the middleware layer against both the token's claimed `organisationId` and the `x-api-domain` header.

**Don't attempt to work around the scope check.** If you need to call a different organisation's API, sign in to that organisation and obtain a fresh token. Sharing tokens across orgs silently won't work and will always return `403 Forbidden`.

## Error cases

| Status             | Cause                                                                  |
| ------------------ | ---------------------------------------------------------------------- |
| `401 Unauthorized` | Missing header, token expired, or signature invalid                    |
| `403 Forbidden`    | Token valid but scoped to a different organisation than `x-api-domain` |
| `404 Not Found`    | `x-api-domain` points to a subdomain that doesn't exist                |

## Where to get a token

Bearer tokens are minted by the Nudj auth layer when a user signs in. Two common paths:

1. **Interactive admin session**: sign into the admin panel at `https://{subdomain}.nudj.cx/admin`. The session cookie is exchanged for a Bearer token on each admin API call automatically.
2. **MCP client**: follow the [MCP Bearer + Domain header pattern](/developer/mcp/bearer-and-domain) — `mcp-remote` and Claude Code inject both headers from a token copied out of the admin panel.

## Security considerations

<Warning>
  Treat Bearer tokens like session cookies. Never commit them, never log them, and never share them across organisations.
</Warning>

* Store tokens in OS keychains or secret managers, never in source.
* Rotate tokens when a team member leaves or any suspicion of compromise.
* The middleware-level org scope check is a defence-in-depth measure, not a replacement for least-privilege RBAC on the token itself.

## Related

<CardGroup cols={2}>
  <Card title="x-api-token Authentication" icon="key" href="/api-reference/authentication">
    The long-lived token path for headless integrations.
  </Card>

  <Card title="MCP Bearer + Domain Headers" icon="plug" href="/developer/mcp/bearer-and-domain">
    How AI clients (Claude, Cursor) configure the headers.
  </Card>
</CardGroup>