Directory Sync (SCIM)

Directory sync provisions and deprovisions your users and groups in airlock automatically from your identity provider using the SCIM 2.0 protocol. When someone joins, changes teams, or is offboarded in your directory, the change flows into airlock without anyone touching the Control Room. Directory sync is best supported with Microsoft Entra ID.

This guide walks through the full setup: configure the provider in airlock, mint a secret token, install and connect the provisioning app in your identity provider, then turn sync on.

Before you start

• You must be an organization admin in airlock. Directory sync lives under Settings → Organization → Directory Sync, which only admins can see.
• You need admin access to your identity provider to create an enterprise/provisioning application (in Entra, the Application Administrator or Global Administrator role).
• For Microsoft Entra ID, have your directory (tenant) ID handy — the GUID from your Entra app registration or tenant overview.

Follow the steps in order. You configure and enable directory sync in airlock first (Steps 1–3), then connect your identity provider (Step 4). Enabling sync in airlock before you run your provider's Test Connection is what makes that test pass: airlock rejects every SCIM request with 403 until sync is enabled, so testing or provisioning against a disabled org is guaranteed to fail (see Troubleshooting).

Step 1 — Configure the provider in airlock

1. Go to Settings → Organization → Directory Sync.

2. Under Identity provider, choose your Provider type: Microsoft Entra ID, Okta, Generic SAML, or Generic OIDC.

3. If you chose Microsoft Entra ID, paste your directory (tenant) ID into the Microsoft Entra tenant ID field. This is required — it binds sign-in for your synced users to your tenant. (An Issuer URL field is available but optional for Entra.)

   This does more than label your provider. Once directory sync is enabled (Step 3) with Entra selected and a tenant ID set, airlock pins Microsoft sign-in for your organization to that tenant: a member signing in with a Microsoft account from any other tenant — including a personal Microsoft account or a guest account, which carry no matching tenant claim — is refused with access_denied. Make sure everyone who signs in with Microsoft is in the tenant whose ID you paste here.

   • If you chose Generic OIDC, the Issuer URL is required instead.
   • Okta and Generic SAML need no extra fields at this step.

4. Click Save configuration.

Step 2 — Generate a secret token

1. Still on Settings → Organization → Directory Sync, find the Connection details card.
2. Click Generate token.
3. Copy the token immediately. It starts with alk_scim_ and is shown exactly once — if you lose it, rotate to mint a new one. Airlock only stores a hash, so it can never show you the value again.

You will paste this token into your identity provider's Secret Token field in the next step, alongside the SCIM base URL.

Also from the Connection details card, copy the SCIM base URL (Tenant URL). For production this is:

https://api.air-lock.ai/scim/v2

(Staging uses https://api.staging.air-lock.ai/scim/v2. Use the exact value shown in your Control Room — copy it from the card rather than typing it.)

Step 3 — Enable directory sync in airlock

1. Still on Settings → Organization → Directory Sync, toggle Enable directory sync on.
2. Click Save configuration.

The toggle is part of the form — flipping it does nothing until you Save. While it is off, airlock rejects every SCIM request with 403 Forbidden even when the token is valid, so your identity provider's Test Connection and provisioning runs fail until sync is enabled and saved. Enabling it now — before you connect your identity provider — means the connection test in the next step succeeds on the first try. Reload the page to confirm the toggle stays on; if it snaps back off, it wasn't saved.

Step 4 — Install and connect the app in your identity provider

These steps use Microsoft Entra ID. Other SCIM 2.0 providers follow the same shape — create a provisioning app, then supply the base URL as the Tenant URL and the alk_scim_ token as the Secret Token.

1. In the Azure portal, open Microsoft Entra ID → Enterprise applications.
2. Click New application → Create your own application.
3. Name it (for example, Airlock), choose Integrate any other application you don't find in the gallery (Non-gallery), and click Create.
4. Open the new application and go to Provisioning → Get started (or Provisioning in the left menu), then set Provisioning Mode to Automatic.
5. Under Admin Credentials, enter:
   • Tenant URL — the SCIM base URL from Step 2:

     https://api.air-lock.ai/scim/v2

   • Secret Token — the alk_scim_... token from Step 2.
6. Click Test Connection. Entra sends an authenticated probe to airlock; a green result means the URL and token are accepted. If it fails, see Troubleshooting.
7. Click Save.
8. Under Users and groups, assign the users and groups you want provisioned into airlock.
9. Back on the Provisioning page, set Provisioning Status to On and start provisioning.

Entra sends the token to airlock on every request as an HTTP Authorization: Bearer alk_scim_... header. Airlock resolves it to exactly one organization — yours — and applies the change there.

Authentication

Directory sync authenticates with a per-organization bearer token, separate from user sign-in and from MCP tokens.

• The token is prefixed alk_scim_ and is sent as Authorization: Bearer alk_scim_... on every SCIM request.
• Airlock stores only a SHA-256 hash of the token — the plaintext exists only in the one-time reveal after you generate or rotate it.
• Each token maps to a single organization, so a token issued for your org can only provision your org.
• Rotating the token replaces it immediately; your identity provider stops syncing until you paste the new token into it.
• Revoking the token deletes it and turns off directory sync. Generating a new token does not turn sync back on — after revoking you must generate a new token, paste it into your identity provider, and then re-enable Enable directory sync and click Save configuration (Step 3).

The discovery endpoints (/scim/v2/ServiceProviderConfig, /scim/v2/Schemas, /scim/v2/ResourceTypes) and the /Users and /Groups resources all require this token.

What gets synced

• Users — created from your directory as airlock members. The userName becomes the user's email; externalId, first name, and last name are carried over. New users land in an invited state with no password — they sign in with your identity provider.

  userName must be an email address — airlock uses it as the member's login identity. If your provisioning app maps userName to anything else (an object ID, a mail nickname, a domain-less account name), each user fails with 400 userName must be an email address. Map it to userPrincipalName or mail instead.

• Groups — synced as airlock groups, with membership kept in step. Because airlock access grants can target a group, synced group membership flows straight into who-can-use-what with no extra configuration.

  Deleting a group in your directory deletes it in airlock, along with all of its memberships — unlike users, which are only deactivated. Any access grant that targeted that group stops granting access to its former members immediately, and re-creating the group in your directory brings it back as a new, empty group you must re-assign.

• Deprovisioning — deleting a user in your directory, or marking them inactive, deactivates the airlock user and revokes their live sessions, so their airlock sign-in stops working too.

  Reactivating is not a clean round trip. A user who had never signed in to airlock is provisioned normally on their next sign-in. A member who had already signed in comes back in the invited state rather than active — their sign-in succeeds, but airlock and MCP calls are refused with "Account not active".

  There is currently no Control Room action that returns an invited member to active: the Users tab offers only Resend and Cancel on an invited row, and the Approve action applies to pending self-signups. Contact airlock if you need a reactivated member restored.

Limits

Airlock returns at most 200 users per /Users request and does not implement paged enumeration (startIndex is ignored). Microsoft Entra is unaffected in practice — it looks users up individually by userName or externalId — but a provider that syncs by listing the whole directory (Okta's initial sync does) will only ever see the first page. If your directory has more than ~200 members, contact airlock before turning sync on. Group listing is unpaged as well.

Roles are not assigned by SCIM. Every user provisioned through directory sync is created as a regular member (role USER). Directory sync never grants the admin role — promote admins manually inside airlock. Group membership grants access to tools and resources, not organization-admin privileges.

Rotating and revoking the token

From Settings → Organization → Directory Sync → Connection details:

• Rotate — mints a new token and invalidates the old one immediately. Paste the new token into your identity provider's Secret Token field right away, or provisioning will stop. The new token is shown once. Rotating does not touch the Enable directory sync toggle.
• Revoke — deletes the active token and switches Enable directory sync off. Resuming provisioning takes three steps, not one: generate a new token, paste it into your identity provider's Secret Token field, then turn Enable directory sync back on and click Save configuration. Generating a token on its own does not re-enable sync — skip the last step and every request comes back 403 "SCIM is disabled for this organization".

Troubleshooting

If a "Test Connection" or provisioning run fails, the fastest way to identify the cause is to look at the HTTP status and response body. You can reproduce the exact call your identity provider makes with the command below. It reads the token from a hidden prompt and passes it through curl's config on stdin, so the token never lands in your shell history or in a process listing — treat it as a live credential and keep it out of logs and support tickets.

read -rs -p "SCIM token: " SCIM_TOKEN; echo
printf 'header = "Authorization: Bearer %s"\n' "$SCIM_TOKEN" \
  | curl -i --config - "https://api.air-lock.ai/scim/v2/Users?count=1"
unset SCIM_TOKEN

A 200 response with an empty user list is not an error — it simply means no matching users, which your identity provider accepts.

The tell-tale sign for the two most common cases: a 403 "SCIM is disabled" means the token is valid but the toggle is off (finish Step 3), while a plain-JSON 404/403 with a message field means your provider never reached airlock's SCIM handler — the URL is wrong.