Authentication — airlock docs

Airlock handles authentication at multiple levels: user authentication to the Control Room, and API authentication for connecting to target services.

User Authentication

Users authenticate to the airlock Control Room using one of:

Email & password — standard email and password login.
Google — sign in with a Google account (consumer Gmail or Google Workspace).
Microsoft — sign in with a Microsoft Entra ID (work or school) account.

Signing in (or signing up) requires accepting the Terms of Service and Privacy Policy — the sign-in screen asks for acceptance before the flow can start.

You can sign in to the same account with more than one provider, as long as each provider has verified your email address. If you first sign up with Google using you@example.com and later sign in with Microsoft on the same verified email, airlock recognizes that both providers have proven control of the same address and links the new provider onto your existing account — you land in the same account either way.

The one case airlock refuses is when the new provider has not verified your email. Because an unverified email can't prove ownership, airlock declines to link it to an existing account and shows a message asking you to verify your email with that provider or sign in with your original method.

Organization Membership

Each user belongs to an organization. Organizations provide:

Isolated data (integrations, policies, users)
Shared billing and quotas
Team collaboration

For organizations on Microsoft Entra ID, airlock supports additional enterprise controls:

Directory sync (SCIM) — provision and deprovision members automatically from your identity provider. Admins configure this under Settings → Organization → Directory Sync. When a user is offboarded in your directory, their airlock sign-in stops working too. See the Directory Sync (SCIM) guide for full setup steps.
Tenant enforcement — once you configure directory sync against a specific Microsoft Entra tenant (a pinned tenant ID with directory sync enabled), Microsoft sign-ins for your existing members must come from that tenant; a sign-in presenting a different tenant is refused. Tenant enforcement is part of the directory sync configuration — pinning a tenant ID without enabling directory sync enforces nothing.

API Authentication

When connecting AI agents to APIs through airlock, credentials are handled per-user.

Built-in OAuth Integrations

Several integrations — GitHub, Google Calendar, Gmail, Google Drive, Vercel, Slack, Figma, Bitbucket, Azure DevOps, Microsoft Teams, Outlook, Outlook Calendar, OneDrive, and Dynamics 365 CRM, plus Dynamics 365 Finance & Operations (coming soon) — have pre-configured OAuth credentials managed by airlock. You don't need to register your own OAuth app; just click Connect and authorize:

Go to your integration's detail page
Click the Connect button
Complete the authorization flow in the popup window
Airlock securely stores your OAuth tokens

OAuth tokens are automatically refreshed when they expire.

Standard OAuth Integrations

Most pre-built integrations (Notion, Linear, Atlassian, etc.) use standard OAuth with the upstream service. The flow is the same — click Connect and authorize.

API Key Integrations

For services that use API keys or bearer tokens (e.g., Datadog, custom APIs):

Go to your integration's detail page
Enter your API credentials (API key or bearer token)
Click Save

Credential Security

All credentials are protected with KMS envelope encryption at rest:

Each stored credential is encrypted with its own unique AES-256-GCM data key
Data keys are wrapped by an airlock-managed AWS KMS key, and decryption is cryptographically bound to the owning organization and record
Credentials are decrypted only when making API calls

See the Security guide for details.

Service accounts (bot identities)

When the caller isn't a human — a scheduled job, a self-hosted agent, a CI runner — use a service account instead. Service accounts are admin-created bot identities scoped to an organization. They authenticate with long-lived bearer tokens prefixed alk_svc_… (default lifetime 1 year, configurable from 1 hour to 1 year) and are granted access to integrations, skills, and agents the same way users and groups are — see Access Control.

MCP Connection Authentication

When AI agents connect to airlock via MCP, they authenticate using MCP OAuth 2.0:

Add the MCP URL to your AI client (Claude Desktop, Claude Code, Augment, etc.)
The client initiates the OAuth flow automatically
You authenticate in your browser
The client receives access tokens and connects

This happens seamlessly when you add a new connector in Claude Desktop.

Session Persistence

MCP connections stay active without requiring you to re-authenticate:

Access tokens expire after 8 hours and are refreshed automatically
Refresh tokens are valid for 30 days
Your AI client handles token refresh transparently — no action needed on your part

After 30 days the client prompts you to sign in again. Note that disabling an AI client under Settings → Security → Allowed AI clients is a connect-time control: it stops new connections, but a client that is already connected keeps working until its session ends (up to 30 days). To cut off access immediately, deactivate the user — or revoke their personal API token, if that is what they are using.

Controlling which AI clients may connect

Admins can control which AI clients are allowed to complete the MCP OAuth flow for the organization, under Settings → Security → Allowed AI clients.

Well-known clients (Claude, ChatGPT, Notion, Cursor, VS Code) each have an on/off toggle, and you can add your own client by approving its HTTPS redirect URL. Each entry can additionally be scoped to specific user groups, so only members of those groups may connect through that client.

If a user's client is disabled, the connection is refused at sign-in with an invalid_request error. If the client is allowed but the user is outside its group scope, the refusal is an access_denied error instead, so the consent page can offer an account switch. Loopback (localhost) clients are always trusted and cannot be disabled.

Personal API tokens

If your AI client can't complete the browser OAuth flow, you can authenticate to MCP with a personal API token instead. A personal token is prefixed alk_pat_, is bound to you, and carries exactly your own permissions — never more.

An admin must enable them first: Settings → Security → Allow personal API tokens, which is off by default.

Then create one under Settings → Account → Personal API tokens:

Give the token a name and pick an expiry — 30 days, 90 days, or 1 year (the default).
Copy the token immediately; it is shown only once.
Use it as a bearer token on the MCP endpoint:

curl https://mcp.air-lock.ai/org/<your-org-slug> \
  -H "Authorization: Bearer $AIRLOCK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

You can hold up to 25 active tokens. Revoke one from the same panel and it stops authenticating on the very next MCP request. Admins can see and revoke every personal token in the organization from Settings → Security. Turning the org toggle off blocks new tokens but does not revoke existing ones.

Token Security

All tokens are encrypted at rest using AES-256-GCM
Refresh tokens are stored as cryptographic hashes — even a database breach would not expose usable credentials
Tokens are bound to your account and the specific client that requested them
Revoking access from Cognito (e.g., signing out) immediately invalidates all refresh tokens

Best Practices

Use OAuth When Available: OAuth provides better security than static API keys
Rotate Credentials Regularly: Update API tokens periodically
Use Least Privilege: Provide tokens with minimal required permissions
Monitor Usage: Check audit logs for unusual activity
Revoke Unused Access: Remove credentials when no longer needed