Skip to content

API Keys

This page covers the technical details of Nodexa API keys: their format, scope semantics, and how to pass per-provider OAuth tokens in requests.

Key Format

Nodexa API keys follow this structure:

nxk_<base64url-encoded-encrypted-payload>
  • The nxk_ prefix identifies the key as a Nodexa key
  • The payload is an encrypted blob containing the key's scope, organization, and metadata
  • Keys are generated server-side and issued by a platform administrator
  • Keys do not expire automatically — they must be explicitly revoked

Example (placeholder — not a real key)

nxk_eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIn0.abc123xyz.def456uvw.ghi789rst.jkl012mno

Keys are opaque to clients

Do not attempt to parse or decode the payload portion of an API key. The format is internal and subject to change. The only canonical source of truth for a key's scope and metadata is the platform admin panel.

Scope Reference

Scopes control which API endpoints a key may access.

full_access

Permission Value
Call POST /v1/responses Yes
Read/write user claims Yes
Read/write/delete memory Yes
Access all future endpoints Yes

Intended for trusted internal services such as admin tooling or backend orchestration layers.

assistant

Permission Value
Call POST /v1/responses Yes
Read/write user claims No
Read/write/delete memory No

Intended for backend services that integrate chat functionality into an application.

user

Permission Value
Call POST /v1/responses No
Read/write user claims Yes
Read/write/delete memory Yes

Intended for backend services that manage user profile data and memory preferences separately from the chat flow.

Passing Your API Key

See Authentication for the header options. In summary:

x-api-key: nxk_your_key_here

or equivalently:

Authorization: Bearer nxk_your_key_here

OAuth Token Passthrough

Some assistants are configured with tools that act on behalf of a specific user — for example, accessing a user's Google Calendar, reading their GitHub repositories, or posting to their Slack workspace. For these tools to work, you must forward the user's OAuth access token alongside the API request.

The x-user-tokens Header

Pass a JSON object where keys are provider identifiers and values are the corresponding OAuth access tokens:

x-user-tokens: {"<provider_id>": "<access_token>", ...}

Example with multiple providers:

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.a0AfH...", "github": "gho_abc123..."}' \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ASSISTANT_ID",
    "input": "Summarize my open GitHub PRs and my meetings for tomorrow."
  }'

How the Platform Uses These Tokens

  1. The Nodexa platform receives the request with x-user-tokens
  2. When a specialist agent invokes a tool that requires a specific provider's credentials, the platform looks up the token for that provider from the header value
  3. The token is used to make the downstream API call on behalf of the user
  4. Tokens are never stored — they are used for the duration of the single request only

Provider IDs

Provider IDs match the identifiers configured in your Nodexa instance's plugin settings. Common examples:

Provider Typical ID
Google (Calendar, Drive, Gmail) google
GitHub github
Slack slack
Microsoft (Outlook, Teams) microsoft

Contact your Nodexa administrator for the exact provider IDs configured on your instance.

OAuth Required Event

If a tool requires OAuth credentials but none were provided (or the token has expired), the platform will emit an oauth_required event in the SSE stream:

{
  "type": "response.output_item.added",
  "item": {
    "type": "oauth_required",
    "plugin_id": "plugin_abc123",
    "plugin_name": "Google Calendar",
    "provider_id": "google",
    "required_scopes": ["https://www.googleapis.com/auth/calendar.readonly"],
    "auth_url": "https://your-admin.example.com/oauth/google/authorize?state=..."
  }
}

Your application should:

  1. Detect the oauth_required item in the stream
  2. Redirect the user to auth_url to complete the OAuth flow
  3. Store the resulting access token
  4. Re-send the original request with the token in x-user-tokens

See SSE Events — oauth_required for full field documentation.

Key Security Best Practices

Never expose keys in client-side code

Browser JavaScript, mobile apps, and other client-side environments are inherently untrusted. Always route API calls through a backend service you control.

Store keys in environment variables or a secrets manager:

# .env (never commit this file)
NODEXA_API_KEY=nxk_your_key_here

// Access in Node.js
const apiKey = process.env.NODEXA_API_KEY;

Rotate keys periodically: Work with your Nodexa administrator to issue new keys on a regular schedule, especially after any suspected exposure.

Use the narrowest scope needed: If your service only sends chat messages, request an assistant scope key. This limits damage if the key is ever leaked.

Audit key usage: Your Nodexa administrator can review API key usage logs to detect anomalous patterns.