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.

One provider per email

Each email address can only be linked to one authentication provider. If you first sign up with Google using you@example.com, you cannot later sign in to the same account with Microsoft or with an email-and-password login — and vice versa.

If you try to sign up with a second provider on an email that's already in use, airlock rejects the sign-up with a message telling you which provider the email is already linked to. To switch providers, sign in with the original provider and contact support to migrate the account.

Organization Membership

Each user belongs to an organization. Organizations provide:

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

API Authentication

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

Built-in OAuth Integrations

Five integrations — GitHub, Google Calendar, Gmail, Google Drive, and Vercel — have pre-configured OAuth credentials managed by Airlock. 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.

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

Credential Security

All credentials are encrypted at rest using AES-256-GCM:

  • Encryption happens before storage
  • Keys are managed securely
  • Credentials are decrypted only when making API calls

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, max 3 active tokens per account) and can be assigned toolsets the same way users and groups can.

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
  4. 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, or if you revoke access from the Airlock dashboard, the client will prompt you to re-authenticate.

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

  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