A growing set of recipes for common airlock failure modes. If you hit something we haven't documented yet, the audit log and the Security → Security logs feed are the two surfaces with the most diagnostic detail.
My agent says an AI Use Policy signature is required
If every tool call comes back with "AI Use Policy acknowledgement required", your organization has published an AI use policy and switched enforcement on. No tool call was made — nothing was executed, and nothing was denied on its merits.
Open the link in the message (the /policy page in the Control Room), read the policy, and sign it. Then wait a few seconds before retrying — a fresh signature is honoured within about 15 seconds, so an immediate retry may still be refused once. Publishing a new version that requires re-acknowledgement puts you back in the same state.
Approvers: approving a queued request can return a conflict and leave it PENDING when the person who raised it has not signed. That is deliberate — the request is held, not rejected. Once they sign, approve the same request again and it runs.
Admins: enforcement is staged on Settings → AI Policy. Service accounts and service tokens are always exempt; being an admin is not an exemption.
Why is my MCP token getting 403?
A bearer credential that worked yesterday and returns 403 forbidden today is almost always one of these.
"My token suddenly stopped working"
Open Security → Security logs and filter by the Access chip (admin access required — ask an admin if you are a member). An allowlist denial reads "<actor> was blocked by the IP allowlist from <source IP>", and its Detection field names the layer that rejected it: allowlist miss at the org layer (a rule covering every token in the org) or at the entity layer (a per-service-account or per-token override).
If no allowlist denial matches, the 403 is coming from somewhere else in the auth chain:
- Your user account is not ACTIVE yet — still invited, or awaiting admin approval.
- You were removed from the organization.
- The service account behind the token was disabled or deleted.
- For browser-based clients only: the request's
Originis not on airlock's allowlist. - The AI client you are connecting through was disabled under Settings → Security → Allowed AI clients, or you are outside its group scope.
Note that a policy DENY, an exceeded token budget, and a security block do not produce a 403. Those come back as a successful HTTP response carrying an error tool result, so the agent shows an error message while the credential itself is fine. To investigate those, open History, pick the integration involved, and look for an API_EXECUTED row with outcome: failure. The audit view is per-integration, so you must select one first — and an IP-allowlist denial carries no integration, which is why it never appears there.
"I added my IP and saved, but my agent still gets 403"
The agent's egress IP almost certainly differs from the IP your browser was on when you added the entry. If the agent runs from a VPC NAT gateway, a cloud VM, or a CI job, that's usually a different address.
Two ways to check:
- Submit a deliberately-failing call from the agent and read its source IP off the denial in Security → Security logs.
- From the agent host, query an "echo" service (e.g.
curl https://api.ipify.org) to see its egress IP, then add that CIDR to the allowlist.
"My NAT IP rotated and now nothing works"
This is the expected failure mode for cloud egress that uses a pool of NAT addresses. Recovery:
- Open Security → Security logs and filter by Access.
- Read the source IP off the denial.
- Add the new CIDR to the relevant allowlist and save — the org allowlist is on Settings → Security; a per-service-account allowlist is on that service account's detail page.
If the NAT pool churns frequently, prefer the broader containing CIDR. A /16 covers 65,536 addresses; that's usually large enough to cover an entire cloud-provider NAT range without daily edits.
The org-level allowlist applies to every MCP caller — service tokens, personal tokens, and interactive OAuth sessions alike. What is not yet available is a per-user allowlist: you can scope CIDRs per service account or per service token, but not per person.
So for genuinely dynamic egress (developer laptops on residential ISPs) you have two options: leave the org allowlist empty and rely on the policy / approval / security-block layers, or list a CIDR broad enough to cover everyone who connects. An org allowlist that only covers your office blocks every remote member's agent.
Resetting an admin lockout
You cannot lock yourself out of the Control Room UI with the MCP IP allowlist — Cognito governs that sign-in, not the MCP token allowlist. If the lockout modal showed up because you genuinely intended to lock the connection (e.g. jump-host admins managing the policy from outside the allowed range), sign in again from the Control Room and edit the list back.
If you somehow lost Cognito access too, contact airlock support — there's no MCP-side mitigation for a Cognito-side lockout.