AiDial Docs

#API Authentication

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

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.

#API Key Authentication

API keys are the primary method for programmatic and automated direct access to the AiDial API. They are not used by the browser-based portal.

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

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

Example response (success):

{
  "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 is scoped to a specific tenant (client organisation), data environment, and permission level. 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 creation and management is handled by your organisation's administrator or AiDial account manager. If you need an API key, contact your administrator.

#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 the AiDial identity provider. During sign-in, the portal keeps the access token in a secure server-side session boundary. The access token is not exposed through the browser session object. When the portal needs data, it forwards:

Authorization: Bearer <access-token>

The portal strips any browser-supplied X-API-Key header so browser-provided headers cannot influence authentication or audit attribution.

#Bearer-Only Portal Endpoints

Some API endpoint families are portal-only and require bearer-token authentication from the portal. API-key authentication is rejected or treated as out of scope for these flows:

  • Session management — Registering, validating, listing, touching, and revoking portal sessions.
  • MFA lifecycle — Portal-managed MFA status and lifecycle actions.
  • Portal-managed settings — Notification preferences, business hours, call limits, consent notice copy, transfer settings, tenant settings, and entitlements.
  • 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.

#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