Skip to main content
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.
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.

​
How the two differ

x-api-tokenAuthorization: Bearer
IssuerAdmin panel → Developer settingsNudj auth service (NextAuth) at sign-in
AudienceScripts, CI, backend integrationsInteractive user sessions, MCP clients
LifetimeLong-lived (rotate manually)Short-lived (session TTL)
Organisation scopeEmbedded in token claimsEnforced at the middleware by the token + x-api-domain combination
RevocationPOST /auth-config/tokens/{tokenId}/revokeSign out or let the session expire

​
Making a request

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

StatusCause
401 UnauthorizedMissing header, token expired, or signature invalid
403 ForbiddenToken valid but scoped to a different organisation than x-api-domain
404 Not Foundx-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 — mcp-remote and Claude Code inject both headers from a token copied out of the admin panel.

​
Security considerations

Treat Bearer tokens like session cookies. Never commit them, never log them, and never share them across organisations.
  • 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.

x-api-token Authentication

The long-lived token path for headless integrations.

MCP Bearer + Domain Headers

How AI clients (Claude, Cursor) configure the headers.