#Authentication

Except for public status endpoints, AiDial API requests require authentication. Partner integrations should use server-side API keys. AiDial Portal sessions use Zitadel bearer JWTs. Do not embed partner API keys in browser code, mobile applications, or other client-side surfaces.

Production API: https://api.aidial.ai

This page omits environment-specific host names, internal topology, and deployment details.

#API Key Authentication

You authenticate by including your API key in the X-API-Key header of every request.

Header: X-API-Key Generated key format: sk_live_<64_hexadecimal_characters> (72 characters total) Example: sk_live_YOUR_API_KEY_HERE

#Key Lifecycle

Generated API keys are stored as salted SHA-256 hashes, not as plaintext. A key must have active status and must not be past its expires_at timestamp to authenticate.

Requests made with a revoked or expired key receive a 401 Unauthorized response.

The API-key inventory available through AiDial Portal and partner-authenticated API surfaces returns metadata only: id, client, scope, environment, description, status, created time, expiry, nullable last_used_at, and nullable revoke time. Plaintext keys are returned only once at creation or rotation, and stored hashes are never response fields.

#Security: Server-Side Only

Your API key is a secret credential. Follow these rules:

• Never embed your API key in client-side JavaScript, mobile applications, or browser code
• Never commit your API key to version control
• Store your API key in environment variables or a secrets manager
• If your key is compromised, rotate or revoke it immediately through the AiDial Portal

#Bearer Authentication

Bearer authentication is for AiDial Portal sessions and other first-party portal flows. It is not the recommended mode for partner server-to-server integrations unless AiDial explicitly provisions that integration path.

Header: Authorization Format: Bearer <jwt>

Bearer JWT validation requires all of the following runtime configuration. These settings are required and have no fallback defaults:

• ZITADEL_ISSUER
• ZITADEL_AUDIENCE
• ZITADEL_JWKS_URL

The API validates the JWT issuer, audience, expiry, required subject, and RS256 signature via JWKS. The JWT sub is then resolved in the local API metadata store. Tenant-scoped assignments use active portal_users and portal_user_client_assignments records; accepted partner-organisation memberships can also bootstrap partner bearer context for partner flows. The resolved database context supplies role-as-scope, client_id, data_env, safe user metadata, and project ids where applicable.

If bearer authentication is attempted while required Zitadel configuration is missing, the API treats that as server misconfiguration and returns 500 Internal Server Error. If the bearer token is valid but has no active supported portal assignment or partner membership, the request returns 404 Not Found to avoid tenant enumeration. If the portal assignment lookup dependency is unavailable, the request returns 503 Service Unavailable.

#Authentication Precedence

Protected API routes that use the shared authentication dependency resolve credentials in this order:

1. X-API-Key
2. Authorization: Bearer <jwt>

If both X-API-Key and Authorization: Bearer headers are present in the same request, the API key is used and the bearer token is ignored.

Some endpoints impose stricter requirements after authentication. For example, portal-only endpoints may require bearer authentication and gateway-only routes may require a dedicated API-key scope. Check each endpoint page for route-specific scope requirements.

#Data Scoping

Both authentication modes resolve to an AuthContext containing the authenticated client_id, data_env, scope, auth_type, and principal metadata. Bearer contexts may also include safe email/display-name metadata and project ids resolved from the database. All API responses are scoped to that context. You only see resources belonging to your organisation; cross-client data is never returned. Accessing resources outside your scope returns 404 Not Found (not 403 Forbidden) to prevent information disclosure.

Metadata, authentication, portal assignment, project configuration, and routing data come from the local API metadata store on the API host. Analytics and call data are routed by the strict (client_id, data_env) mapping in the tenant routing map; there is no cross-tenant fallback route. A missing route is an API configuration error and returns 500 Internal Server Error. If the routed data host, tunnel, or database is unavailable, the API returns 503 Service Unavailable.

PII-sensitive responses also respect the client-level PII flags in aidial_clients. Phone and transcript decryption goes through server-side decryption pathways before any permitted plaintext is returned. When PII permissions are missing, lookup fails, or decryption fails, the API fails closed by redacting or omitting PII. Raw encrypted fields such as ciphertext, wrapped keys, and *_encrypted database fields are not partner response fields.

#Public Health Endpoints

GET / and GET /v1/health do not require authentication. /v1/health includes API database readiness details, including database.db_writable, for deployment and HA monitoring.

#Error Semantics

#Example

#Successful API Key Authentication

Request:

curl -X GET "https://api.aidial.ai/v1/partner/me" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "client_id": "client_example_001",
  "scope": "partner_admin",
  "data_env": "prod",
  "auth_type": "api_key",
  "api_key_id": 42,
  "api_key_description": "Primary integration",
  "expires_at": null
}

#Authentication Failure

Request (missing credentials):

curl -X GET "https://api.aidial.ai/v1/partner/me"

Response (401 Unauthorized):

{
  "error": "Missing authentication. Provide X-API-Key or Authorization: Bearer token.",
  "status_code": 401
}

#Related Pages

• Error Responses - error format details for all status codes
• Rate Limiting - handling 429 responses
• API Reference - endpoint index and base URL