Skip to content

Authentication

Nodexa uses API keys to authenticate all requests. This page explains how to include your key in requests and what each key scope allows.

API Key Format

Nodexa API keys use the nxk_ prefix followed by a base64url-encoded encrypted payload:

nxk_eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0...

Keys are issued by your Nodexa platform administrator. They are static secrets — treat them like passwords. Never commit API keys to version control or expose them in client-side code.

Never expose API keys client-side

API keys grant access to your platform's AI capabilities and user data. Always use them from a backend service. If a key is compromised, contact your administrator to revoke and reissue it.

How to Pass Your API Key

Nodexa accepts API keys via two HTTP headers. Both are equivalent — use whichever fits your toolchain.

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "Hello" }'

Option 2: Authorization: Bearer header

curl https://your-admin.example.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "Hello" }'

OpenAI SDK compatibility

The OpenAI SDK sends the API key as Authorization: Bearer by default. Both headers are accepted, so the SDK works without any custom configuration.

Key Scopes

Each API key is issued with one or more scopes that control which endpoints it can access.

Scope Accessible Endpoints Typical Use Case
full_access All endpoints Internal services, admin tooling
assistant POST /v1/responses Chat integrations, AI feature backends
user /v1/memory/*, /user-claims/* User profile management, memory opt-out flows

Minimal scope principle

Request only the scopes your integration needs. A key with assistant scope cannot read or write user claims, limiting the blast radius if the key is ever leaked.

Scope Details

full_access

Grants unrestricted access to all API endpoints. Use only for trusted backend services that need to manage both conversation and user data.

assistant

Grants access to POST /v1/responses only. This is the correct scope for a backend service that:

  • Sends user messages to an assistant
  • Receives streamed or non-streamed responses
  • Invokes tools and handles requires_action callbacks

user

Grants access to user-scoped endpoints:

  • GET /user-claims/:userId
  • GET /user-claims/:userId/:claimKey
  • POST /user-claims
  • POST /user-claims/bulk
  • DELETE /user-claims/:userId/:claimKey
  • GET /v1/memory
  • DELETE /v1/memory
  • POST /v1/memory/opt-out
  • DELETE /v1/memory/opt-out
  • DELETE /v1/memory/:itemId

Optional Request Headers

Beyond the authentication header, several optional headers control runtime behavior.

x-user-id

A string identifier for the end user making the request. When provided, the assistant uses this ID to load and save per-user memory.

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "What did we discuss last time?" }'

User ID format

The x-user-id value is an opaque string from Nodexa's perspective. Use whatever identifier is natural for your system (database UUID, hashed email, etc.). Avoid using PII like plain email addresses as user IDs.

x-user-token

A single authentication token for the end user, forwarded as-is to MCP servers during tool calls. This enables MCP servers to verify the user's identity independently, without trusting Nodexa as an intermediary.

The most common use case is forwarding a Firebase ID token so your MCP server can call verifyIdToken() directly:

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-token: eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "Show my saved items" }'

How it flows:

Mobile app (Firebase ID token)
  → Your backend (verifies token, forwards it)
    → Nodexa (x-user-token header)
      → MCP server tool call (x-user-token forwarded)
        → Firebase Admin verifyIdToken() → uid → Firestore ops

Your MCP server receives the token and verifies it:

const decodedToken = await getAuth().verifyIdToken(userToken);
const uid = decodedToken.uid;
// proceed with Firestore operations as this user

When to use x-user-token vs x-user-id

Use x-user-token when your MCP server needs to independently verify the user's identity (e.g., Firebase, Auth0, Supabase tokens). Use x-user-id when Nodexa only needs a user identifier for memory and conversation tracking. You can use both together.

Token handling

Nodexa treats the token as an opaque string — it does not validate or decode it. The token is forwarded to MCP servers exactly as received. Token expiry and verification are the responsibility of the MCP server.

x-user-tokens

A JSON object mapping OAuth provider identifiers to access tokens. Use this when a tool configured on the assistant requires a user's OAuth credentials (for example, accessing Google Calendar or GitHub on behalf of a user).

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-id: user_abc123" \
  -H "x-user-tokens: {\"google\": \"ya29.a0...\"}" \
  -H "Content-Type: application/json" \
  -d '{ "model": "YOUR_ASSISTANT_ID", "input": "What meetings do I have tomorrow?" }'

See API Keys — OAuth Token Passthrough for the full format.

Authentication Errors

HTTP Status Error Meaning
401 Unauthorized missing_api_key No API key header provided
401 Unauthorized invalid_api_key Key is malformed or not recognized
403 Forbidden insufficient_scope Key does not have the required scope for this endpoint

Example error response body:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

See Errors for the full error reference.