Authentication

Nodal has two authentication surfaces: browser sessions for the web app and bearer API keys for the OpenAI-compatible gateway.

App Sessions

The web app uses signed-in user sessions. Session-backed API routes resolve the active workspace and enforce membership before returning workspace data.

Session-authenticated routes include chat sessions, files, knowledge collections, wallet balance, API key management, billing artifacts, and workspace administration.

Gateway API Keys

Gateway requests use bearer keys:

Authorization: Bearer ndk_your_key_here

Keys are scoped to one workspace. When a request reaches /v1/chat/completions, /v1/embeddings, or /v1/models, Nodal authenticates the key, applies rate and spending checks, and bills the key's workspace for billable routes.

Key Management

Workspace members can list key metadata. Creating and revoking keys requires owner or admin membership. Newly created key secrets are shown once; store them in your secret manager.

Common Auth Errors

• 401 invalid_api_key: the bearer token is missing, invalid, or revoked.
• 402 insufficient_funds: the workspace wallet does not have enough available balance for the estimated request.
• 403 workspace_suspended: the workspace is blocked from sending billable traffic.
• 429 rate_limited: the request exceeded an IP, key, or workspace limit.