Authentication

All API endpoints require authentication. ai& supports two methods:

API Key (recommended)

Pass your API key in the Authorization header:

Authorization: Bearer sk-your-api-key

API keys are scoped to an organization. Each key resolves the associated billing account automatically.

Caution

API keys are shown once at creation time. Store them securely — you cannot retrieve the full key later.

Key format

All API keys start with the sk- prefix.

Key management

Create, list, update, and revoke API keys from the console or via the management API:

Action	Endpoint
List keys	GET /api/v1/keys
Create key	POST /api/v1/keys
Update key	PATCH /api/v1/keys/{key_id}
Delete key	DELETE /api/v1/keys/{key_id}

All key management endpoints require the X-Org-ID header set to your organization ID.

From a terminal, aiand login from the ai& CLI signs in through your browser, then creates, stores, and rotates a key for you.

JWT (session auth)

Browser-based clients authenticate via JWT tokens stored in httpOnly cookies. This is used by the console web app and is not recommended for programmatic API access.

• Access token: 15-minute TTL, set as __Host-access_token cookie on the API host only
• Refresh token: 30-day TTL, set as __Host-refresh_token cookie on the API host only

JWTs are issued via OAuth (Google/GitHub), magic link, or SAML SSO sign-in flows.

SAML SSO

Enterprise tenants can enable SAML SSO (Okta, Entra ID, and other IdPs) instead of Google/magic link sign-in. SAML termination is handled by WorkOS; ai& treats it as an OAuth-style redirect:

1. The console redirects to GET /auth/login/workos, which sends the browser to the WorkOS AuthKit sign-in page. No organization or domain is passed in.
2. The user enters their work email address on that page. WorkOS picks the SSO connection from the email domain and sends the user to your IdP.
3. After the IdP redirects back, GET /auth/callback/workos exchanges the result for a session, following the same cookie-based flow as the other sign-in methods.

Only sign-ins that actually went through an SSO connection are accepted. A sign-in through AuthKit’s own password or social options is rejected, even for an email domain that is registered to an organization. An SSO sign-in is also accepted only when the email address is on one of your company’s verified domains, so only existing accounts with such an address can be merged through SSO.

The first person to sign in from your company creates the organization in ai& and becomes its Admin. Everyone after that joins the same organization as a Member. Removing a member in ai& does not block them from signing in again: while their account is active in your IdP, their next SSO sign-in adds them back. To offboard someone for good, deactivate them in your IdP as well.

For email domains that require SSO, Google and GitHub sign-in redirect back to the console with an sso_required error, and magic link requests return a 403 — in both cases the user is directed to sign in via SSO instead. Contact your account team to enable SSO for your organization.

Organization context

API keys are bound to an organization. When authenticating with an API key, the organization is resolved automatically from the key.

When using JWT auth, pass the X-Org-ID header to specify which organization context to use.

Error responses

Status	Meaning
401	Missing or invalid credentials
402	Insufficient credits in the billing account
403	Valid credentials but insufficient permissions

See Error Codes for the full error response format.