Tokens

A token is how a machine — an AI agent, a CI job, or an SSH session — authenticates to Veil Keys. Tokens are not secrets you store; they’re scoped, revocable keys that let something use your credentials within strict limits. There are three kinds, and they are walled off from one another: each kind works only on its own surface.

The isolation model

Three rules govern every token, regardless of kind:

1. Surface isolation. Each token kind only works on its own surface. An agent token drives the MCP broker and nothing else; a CI token works only with veil run; an SSH token works only with the SSH agent. A token presented to the wrong surface is refused.
2. Narrowing only. A token can only narrow the access of whoever created it — never widen it. If you don’t have reveal, no token you mint can reveal. Scopes subtract; they never add.
3. Hashed and revocable. Tokens are stored hashed, never in plaintext. You can revoke any token instantly, which immediately stops every session using it.

Token kinds at a glance

Agent token (veil_agent_…)

Drives the MCP broker — and only the MCP broker. This is the token you give Claude Code, Cursor, or any MCP client so it can use your services via call_api, list_services, and create_service.

Scopes you can set:

• Tools — which MCP tools are allowed: list_services, create_service, call_api.
• HTTP methods — which methods call_api may use, from GET through DELETE. Restrict to GET for a read-only agent.
• Workspace — optionally bind the token to a single workspace.

An agent token can never read a plaintext secret and can never sign. It can only ask the broker to use a credential, so the agent gets working API calls while the value stays sealed.

CI token (veil_ci_…)

Works only with the veil run command. Because veil run injects plaintext secrets as environment variables into a child process, a CI token can return plaintext — which is exactly why minting one requires the reveal permission.

Scopes you can set:

• Workspace — optionally bind to a single workspace.
• Service allowlist — optionally restrict the token to a specific list of services, so a leaked CI token can’t resolve anything outside that list.

Store the veil_ci_… value as a secret in your CI provider and expose it to the job as VEIL_TOKEN. See the CLI reference and CI injection.

SSH token (veil_ssh_…)

Works only with veil ssh-agent. It lets the agent ask Veil to sign SSH authentication challenges; it is gated by the use permission and can be bound to a workspace. It never returns the private key — only signatures.

See SSH brokering.

Creating and revoking tokens

Mint every token in the app’s Security section. Choose the kind, set its scopes, and copy the value — it is shown once and never again, because Veil stores only its hash.

Choosing the right token

Next steps

• Quickstart — mint an agent token and make your first brokered call.
• CLI reference — veil run and veil ssh-agent.
• Security overview — where tokens sit in the trust model.