Access Tokens

Access tokens are how external clients authenticate to Infracodebase: AI agents in your IDE, CI pipelines, scheduled jobs, and any custom integration. Every token is sent as a Bearer credential against the same /api/... endpoints the web app uses, so anything you can do in the UI you can do with a token.

There are two types of tokens, and they're shaped for different jobs.

Personal vs. enterprise tokens

Personal access tokens belong to a single user and carry that user's permissions. Use them when you want to act from another tool, like connecting Claude Code, Cursor, or Claude Desktop to your workspaces, or running a script from your laptop. They're the right default for IDE integrations.

Enterprise access tokens belong to the enterprise itself, not a person. They carry a configurable subset of permissions chosen at creation time, and can be scoped to all or a specific set of workspaces. Use them for CI pipelines, scheduled jobs, and automations that should outlive any individual's membership. They keep working when a member leaves the enterprise; a personal token doesn't.

Personal access tokens

Open Access Tokens in your account settings and click Create token. You'll be asked for:

• Name: a label so you can find this token later in the list
• Scopes: read lets the token call read-only tools and endpoints. execute adds write access like creating workspaces, linking repos, and updating attached resources.
• Expiration: 7, 30, 90, or 365 days, or never. The default is 90 days.

The token value (starting icb_pat_...) is shown once at creation. Copy it immediately. Infracodebase only stores a hash of it, so if you lose the value you'll have to create a new token. There's no "show again."

Enterprise access tokens

Open Tokens in your enterprise settings and click Create token. You need the Manage enterprise access tokens permission (enterprise.tokens.manage) to create or revoke tokens.

You'll be asked for:

• Name: what you call this token in the manager
• Permissions: a set of granular permissions grouped by domain (billing, workspaces, rulesets, secrets, integrations, and so on). The list is the same permission catalog used by custom roles.
• Workspace scope: either All workspaces (the token can reach any workspace in the enterprise, including ones created later) or Specific workspaces (the token can only see and act on the workspaces you pick).
• Expiration: same presets as personal tokens.

The token value (starting icb_eat_...) is shown once, at creation. Copy it immediately.

What you can and cannot grant

Three rules apply to the permissions a token can carry. They protect against a token quietly granting more authority than its creator has.

1. You cannot grant permissions you don't hold. The permissions you can stamp on a token are intersected with your own effective permissions at the enterprise. If you don't have enterprise.secrets.manage, you cannot mint a token that has it.
2. Token management cannot be delegated. Tokens cannot include enterprise.tokens.manage or enterprise.tokens.view. Otherwise a token could mint or inspect other tokens.
3. Enterprise deletion and role assignment cannot be delegated. Tokens cannot include enterprise.delete or enterprise.members.roles.assign. The second prevents a privilege-escalation path where a token holder could grant themselves Owner.

Tokens are immutable after creation. To change what a token can do, revoke it and create a new one.

When members leave

Enterprise tokens are owned by the enterprise, not the user who created them. If that user is removed from the enterprise or leaves the company, their enterprise tokens keep working. The audit log preserves who originally created each one, so you have a clean record even after the creator is gone.

Using a token

Send the token as a Bearer credential on the Authorization header.

Authorization: Bearer icb_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The same header works against the MCP server and the REST API. Both token types are accepted on both surfaces, and the server picks the right verification path from the prefix.

A common pattern for CI:

curl -s https://app.example.com/api/enterprises/$ENTERPRISE_ID/workspaces \
  -H "Authorization: Bearer $INFRACODEBASE_TOKEN"

Store tokens in your CI provider's secret manager. Never commit them to source control.

Rotation and revocation

Each token has a Revoke action in its manager. Revocation takes effect immediately. The next request from that token returns 401 Unauthorized. There is no grace period.

To rotate a token:

1. Create a new token with the same scopes or permissions
2. Update your client or CI configuration to use the new token
3. Revoke the old one once the new one is in place

Tokens you haven't used recently show a Last used timestamp in the manager. Empty Last used columns are a good place to start when cleaning up.

Security model

• Token values are never stored. Only an HMAC keyed by Infracodebase's master key is persisted, so a database snapshot cannot be replayed against the API.
• Token plaintext is shown exactly once, at creation.
• Each verified call updates a Last used timestamp so you can spot stale tokens.
• Enterprise token creation and revocation are recorded in the enterprise audit log, with the actor and a description of what was granted.

Troubleshooting

• 401 Unauthorized: token is missing, malformed, revoked, or expired. Check that the Authorization header starts with Bearer icb_pat_ or Bearer icb_eat_.
• 403 Insufficient permissions: the token's permissions don't include the action you're calling. For enterprise tokens, open the token in the manager and confirm the permission is stamped on it.
• 429 Too Many Requests: exceeded the per-token rate limit. Back off and retry.
• An enterprise token works for some workspaces but not others: workspace scope is set to a subset that doesn't include the workspace you're targeting. Revoke and recreate with the right scope.