Guides

Authentication

How users sign in to the Control Room, how agents authenticate via MCP OAuth, and how per-user credentials are stored.

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, and the sign-in screen asks for acceptance before the flow can start.

Linking multiple sign-in providers

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, so 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

Enterprise Sign-in Controls

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, so 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 by default: each person connects their own account or key, and calls run as them. For an integration that takes an API key, an admin can share one credential with the team instead (see Shared team connections).

Built-in OAuth Integrations

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

  1. Go to your integration's detail page
  2. Click the Connect button
  3. Complete the authorization flow in the popup window
  4. airlock securely stores your OAuth tokens

OAuth tokens are automatically refreshed when they expire.

If an integration later starts asking for a permission your connection never granted, Your connection on its Settings tab says This connection is missing a permission; click Reconnect Account to grant it.

Sign-in or API key

Slack and Vercel take either a sign-in or an API key. When an admin adds one, the wizard asks How do you want to connect? (Sign in or Use an API key). Either way, every member can choose for themselves under Your connection on the Settings tab: to move from a sign-in to a key, click Switch Account to disconnect, then paste the key (an expired sign-in shows Disconnect and use an API key instead).

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

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

For most integrations airlock tries the credential against the provider before storing it:

  • Refused: nothing is saved, and the provider's reason is shown so you can fix the key and try again.
  • Accepted: the key is saved and marked Verified with the provider.
  • Could not be checked: the key is saved, with a note that it could not be verified.

A key that worked when saved can stop working later, for example when someone revokes it at the provider. airlock then flags the member's own connection with Credentials rejected by <integration> on <date> and asks them to replace it, rather than showing it as connected. Admins see how many members' credentials were rejected under Your connection on the integration's Settings tab.

Shared team connections

By default every member brings their own credential. For an integration that takes an API key, an admin can share one instead: on Connectors, open the integration's ⋯ menu and choose Share with your team, then store one credential (for a custom MCP server, together with values for its extra headers). Then choose under Who can use it which people and spaces may call through it; nobody can until they are granted.

The owner of the space an integration lives in can share it too, with that space or with people in it. When nobody has been given it yet, sharing gives it to the integration's space straight away, unless that space is open to anyone in the organization; then pick the people instead. If it was shared before, the people and spaces it was shared with get it again. An integration that lives in the Organization space is shared by an admin.

On Connectors a shared integration is marked Shared: for the people who use it, and for whoever manages it, together with how many it is shared with. Sharing not finished means the switch is on but no key is stored yet, or nobody has been granted it.

Off (default)On
Whose credential a call usesThe member's ownThe one stored by the admin, unless the member saved their own
Members see the credentialTheir own onlyNever
Who can use itEveryone with access to the integration, once connectedOnly those granted under Who can use it

Once it is shared, the same menu entry reads Sharing settings: change the key, change who can use it, or Stop sharing. Stopping removes the key and everyone goes back to connecting their own credential; who it was shared with is kept, so sharing again needs no re-granting. Integrations that sign each person in individually (OAuth only) cannot use a shared credential.

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, such as a scheduled job, a self-hosted agent, or 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 spaces are, except that a service account starts with nothing and inherits no open default. See Access Control.

MCP Connection Authentication

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

  1. Add the MCP URL to your AI client (Claude Desktop, Claude Code, Augment, etc.)
  2. The client initiates the OAuth flow automatically
  3. You authenticate in your browser. The authorization screen shows who you are Signed in as (your email and organization) before you click Authorize; if that is the wrong account, click Use a different account
  4. The client receives access tokens and connects

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

Microsoft 365 Copilot stores the sign-in details differently and asks for a Reference ID. See the Microsoft 365 Copilot guide for the exact values to enter. Gemini Enterprise takes a fixed client ID instead; the Gemini Enterprise guide lists every field.

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, with no action needed on your part

After 30 days the client prompts you to sign in again. Disabling, removing, or re-scoping an AI client under Rules → Allowed AI clients is checked at sign-in and again every time a session refreshes, so a client that is already connected stops within 8 hours at most. 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 Rules → Allowed AI clients.

Well-known clients (Claude, ChatGPT, Notion, Cursor, VS Code, Microsoft 365 Copilot, Gemini Enterprise) 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 spaces, so only members of those spaces 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 space 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.

If a client airlock does not recognize tries to connect, the sign-in error names its callback, for example This application's callback (https://app.example.com) is not approved for your organization, and offers a button to copy that address. An admin can paste it as a custom client under Rules → Allowed AI clients; then try connecting again. See Troubleshooting.

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. Where your organization uses the LLM gateway, the same kind of token is also the key for model calls.

An admin must enable them first, on the Rules page under What is connected → Personal API tokens. There are two switches, both off by default: MCP & skills (tokens for the MCP endpoint) and LLM gateway (tokens for model calls, shown only where the gateway is on). In an organization that had personal tokens turned on before the two were split, the LLM gateway switch starts out matching MCP & skills. From the first time either switch is saved, the two are set separately.

Then create one under Settings → Account → Connect your AI tools, where your MCP endpoint (and LLM gateway address) are listed too:

  1. Give the token a name and choose what it is for: MCP & skills, LLM gateway, or both, out of what your organization allows. A token only works where it was made for.
  2. Pick an expiry: 30 days, 90 days, or 1 year (the default).
  3. Copy the token immediately; it is shown only once.
  4. For a token made for MCP & skills, use it as a bearer token on the MCP endpoint, as below. A token made only for the LLM gateway is refused there; use it as the key for model calls instead, as the AI models guide describes.
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 its very next request. A token made for the LLM gateway only is refused on the MCP endpoint (403), and the reverse. Tokens created before this choice existed work for both.

Admins see every personal token in the organization, grouped per person, under Settings → Security → Personal API tokens. From there they can revoke one token, all of one person's tokens, or every token at once; the last two ask you to type revoke all first. Turning a switch off on the Rules page 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, so 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

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