#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 portal middleware. Portal API paths pass straight through middleware without an authentication check, so route handlers under /api/** enforce their own authentication, RBAC, mutation protection, and tenant/project scope.

#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

The response container for GET /v1/projects depends on your key's scope. Keys with a partner or internal scope (partner_admin, partner_user, aidial_admin, aidial_operator) receive a paginated envelope, and accept page, page_size, sort_by, sort_order, data_env, include_inactive, and include_archived query parameters:

JSON
{
  "items": [
    {
      "project_id": "example-project-id",
      "client_id": "example-client-id",
      "display_name": "My Project",
      "timezone": "Australia/Sydney",
      "is_active": true
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_records": 1,
    "total_pages": 1
  }
}

Keys with a customer scope receive an unpaginated projects array containing the same project objects. Both examples are abbreviated; each project object carries additional fields, including billing configuration and creation/update timestamps.

#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 on the portal's Integrations page, under the API keys tab, for authorized roles. 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 and aidial_admin can view API-key metadata and create, rotate, or revoke keys.
  • partner_user and aidial_operator can view API-key metadata but cannot create, rotate, or revoke keys.
  • Customer roles cannot reach these routes at all.

Every one of these routes requires an explicit in-scope client selection; a request without one is rejected. Create, rotate, and revoke are mutations and are CSRF-protected.

The list response returns key metadata only — never the secret value. The plaintext key is returned once, in the create and rotate responses, and is not retrievable afterwards.

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 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 server-side portal transport 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.

#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.

Resolving the server-side session also re-checks the actor's MFA state and tenant lifecycle status on every request. A session that is not MFA-compliant for its role receives the same non-enumerating 404; a non-active tenant is rejected with a 403 or 409. See Error Responses for the full list.

#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