Service Accounts

A service account is a bot identity inside an organization. Use one when you want an AI agent, automation, or long-running script to call airlock without being tied to a specific human user — for example, a CI job or a background agent.

Service accounts authenticate with service tokens, not OAuth. They can be assigned toolsets the same way a user or group can.

When to use a service account

• A scheduled job that needs to call MCP tools on its own schedule.
• A self-hosted agent that should keep working when no human is signed in.
• A CI/CD pipeline that calls airlock from a build runner.
• An agent runtime that needs persistent, non-interactive access.

If a real person is driving the calls, use their normal user sign-in instead.

Creating a service account

Service accounts are an admin-only feature. Open Settings → Service Accounts (or go directly to /service-accounts) in the Control Room.

1. Click New Service Account
2. Give it a descriptive name (e.g. nightly-research-bot)
3. Optionally add a description so other admins know what it's for
4. Click Create

The new service account is created in ACTIVE status, scoped to your organization. It has no credentials yet — you mint those separately in the next step.

Issuing a service token

Service tokens are the credentials a service account uses to call MCP. They look like this:

alk_svc_<random>

The alk_svc_ prefix lets you recognise an airlock service token in logs and dashboards.

1. Open the service account's detail page
2. Click New Token
3. Optionally pick a custom lifetime (between 1 hour and 1 year; default is 1 year)
4. Click Generate
5. Copy the token immediately — airlock only ever shows the full value once

After that, only the prefix (alk_svc_XXXXXXXX) is visible in the Control Room. The full token is hashed with SHA-256 before storage; even airlock admins can't recover it.

Expired tokens are cleaned up automatically (DynamoDB TTL); revoked tokens stay visible in the audit trail but stop authenticating immediately.

Org-wide vs service-account tokens

There are two flavours of service token:

Prefer service-account tokens whenever possible — they make audit trails and toolset scoping much cleaner.

Using a service token

Pass the token as a bearer token on the MCP HTTP endpoint:

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

The same token works for every MCP method (tools/list, tools/call, prompts/list, etc.) the service account is authorised to use.

Toolset assignments

Service accounts can be assigned toolsets just like users and groups. A toolset is a curated bundle of tools — assigning one to a service account is how you grant it access to specific MCP tools without giving it everything.

In the Control Room, open the service account's detail page and use Toolsets → Assign to attach one or more toolsets. The service account immediately sees those tools on its next tools/list call.

Disabling and revoking

You have two levers, depending on how surgical you want to be:

• Revoke a single token — invalidates that one credential immediately. Other tokens on the same service account keep working.
• Disable the service account — flips its status to DISABLED. All tokens on the account stop working at once, but the account itself (and its toolset assignments) is preserved so you can re-enable it later.

Disabled accounts can be re-enabled from the same screen; revoked tokens cannot — you'd issue a new one.

Security notes

• Tokens are stored hashed (SHA-256); only the prefix is recoverable from storage.
• Treat service tokens like passwords: never commit them to git, prefer your platform's secret manager, and rotate them well before the expiry date.
• All token creation, revocation, and service-account changes are written to the audit log with the admin's identity.
• A revoked or expired token returns 401 Unauthorized on its next MCP call — agents using it should refresh or fail loudly rather than retrying silently.
• Service accounts bypass approval workflows, so airlock recommends pairing them with an IP allowlist as a compensating control. See Network access for the per-organization and per-service-account allowlists.