#API Authentication

6 min read

#Overview

AiDial uses two authentication methods, depending on the caller:

  • API keys for direct partner, integration, and server-to-server calls to the AiDial API.
  • Bearer tokens for first-party AiDial Portal sessions. Portal browser traffic goes to the portal server first, then the portal server calls the AiDial API with a bearer token.

The AiDial Portal follows a Backend-for-Frontend (BFF) model:

text
Browser -> AiDial Portal server -> AiDial API

The browser must not send X-API-Key to the portal or to the AiDial API. API keys are for trusted server-side integrations only. Portal routes enforce authentication, role permissions, applicable CSRF checks, and tenant/project scoping before forwarding server-side requests.

Non-API page routes are guarded by middleware.ts; route handlers under app/api/ enforce their own authentication, RBAC, mutation protection, and tenant/project scope because /api/ is intentionally excluded from middleware rewriting.

#API Key Authentication

API keys are the primary method for programmatic and automated direct access to the AiDial API from trusted server-side systems. They are not used by browser-based portal traffic, including portal screens that manage API-key inventory.

#How to Use an API Key

Include your API key in the X-API-Key header of each direct API request that uses API-key authentication:

HTTP
GET /v1/projects HTTP/1.1
Host: api.aidial.ai
X-API-Key: your-api-key-here

Example response (success):

JSON
{
  "projects": [
    {
      "project_id": "example-project-id",
      "client_id": "example-client-id",
      "display_name": "My Project",
      "timezone": "Australia/Sydney",
      "is_active": true
    }
  ]
}

#API Key Scope

Each API key resolves in aidial_api to an auth context containing a tenant (client_id), data environment, and permission scope. Your key determines which endpoints and actions you can access. If you attempt to access a resource outside your key's scope, the API returns a non-enumerating error response such as 404 Not Found. See Error Responses for details.

#Obtaining an API Key

API-key lifecycle is available in the portal's Integrations area for authorized roles. Current portal BFF routes under /api/partner/api-keys/** use the signed-in user's bearer session to list, create, rotate, and revoke keys through aidial_api; they do not send a browser-supplied X-API-Key.

  • partner_admin can view API-key metadata and create, rotate, or revoke keys for assigned clients.
  • partner_user can view metadata in read-only mode where the portal exposes it.
  • aidial_admin can perform operational API-key actions when an explicit client is selected; aidial_operator has read-only inventory/posture access where implemented.
  • Customer roles do not manage partner API keys.

If you do not have the required portal access, contact your organisation's administrator or AiDial account manager.

#Bearer Token Authentication

Bearer tokens are used by the AiDial Portal to communicate with the AiDial API on behalf of signed-in users. This method is reserved for first-party portal session flows and is not the normal authentication method for direct partner integrations.

Portal sign-in uses next-auth with Zitadel OIDC. During sign-in, the portal stores the access token in the signed HttpOnly NextAuth session cookie. Browser JavaScript cannot read that cookie, and the access token is not copied into the browser session object returned by useSession(). Server-side route handlers extract the token from the verified session and forward:

HTTP
Authorization: Bearer <access-token>

The shared portal transport in lib/aidial-api/ strips caller-provided X-API-Key headers, validates upstream paths as /v1/, sets cache: "no-store", and injects the server-side bearer token so browser-provided headers cannot influence authentication or audit attribution.

#Required Portal Runtime Configuration

The portal runtime requires the following configuration. Current code reads these values through requireEnv() or equivalent required checks and fails closed when they are missing; AIDIAL_API_TIMEOUT_MS must be a positive number.

  • NEXTAUTH_SECRET
  • NEXTAUTH_URL
  • AIDIAL_API_BASE_URL
  • AIDIAL_API_TIMEOUT_MS
  • ZITADEL_ISSUER
  • ZITADEL_CLIENT_ID
  • ZITADEL_CLIENT_SECRET

#Bearer-Only Portal Endpoints

Some portal BFF and backend endpoint families require bearer-token authentication from the portal. API-key authentication is rejected or treated as out of scope for these portal flows, even when adjacent direct integration endpoints exist:

  • Session management — Registering, validating, listing, touching, and revoking portal sessions.
  • MFA lifecycle — Portal-managed MFA status and lifecycle actions.
  • Portal-managed settings — Notification preferences and settings, business hours, call limits, consent notice copy, transfer settings, tenant settings, entitlements, reports, secondary-use/privacy controls, data governance, data deletion, and IP allowlist settings where implemented.
  • Partner and internal portal operations — Partner-team, partner-client, project workspace, portal API-key lifecycle, webhook, SSO, SCIM, tenant, user, incident, discount, adjustment, capacity, and status BFF routes where implemented.
  • Portal authorization and audit flows — Compliance authorization decisions, sensitive-access audit events, and tenant/project scoped portal actions.

These endpoints are designed for authenticated portal users. Browser code should call the portal route handler, not aidial_api directly.

#Portal Route Security

Page access, API actions, tenant scope, project scope, CSRF-sensitive mutations, and compliance-sensitive actions are enforced server-side. Navigation visibility is only a user-interface aid. It is not a security boundary. Out-of-scope resources should return non-enumerating responses such as 404 Not Found.

Implementation source files:

  • Route handlers: app/api/**
  • Shared server-side API transport: lib/aidial-api/**
  • Session, middleware, RBAC, CSRF, and tenant-scope helpers: lib/auth/**
  • Compliance authorization and audit helpers: lib/compliance/**

#Authentication Resolution Order

When both authentication methods are provided to aidial_api in the same request:

  1. API key (X-API-Key header) is checked first.
  2. Bearer token (Authorization: Bearer header) is checked only if no API key is present.
  3. If neither is provided, the request is rejected with a 401 error.

This means that if you include both headers in a direct API request, the API key is used and the bearer token is ignored. The portal strips forwarded X-API-Key headers and sends its own server-side bearer token.

#Best Practices

  • Keep your API key secure — Treat your API key like a password. Do not share it publicly or include it in client-side code.
  • Use the correct method for your use case — Use API keys for direct partner or server-to-server integrations. Use the portal UI or portal BFF routes for signed-in user workflows.
  • Do not bypass the portal BFF — Browser code should call portal route handlers, not aidial_api directly.
  • Keep tenant scope explicit — Use only resources that belong to your authenticated tenant or assigned partner clients. Out-of-scope requests are intentionally non-enumerating.
  • Rotate keys regularly — If you suspect your API key has been compromised, contact your administrator to rotate it.

#Next Steps