Machine identities

Scoped, expiring, revocable credentials for agents and CI

A machine identity is a credential for something that is not a person: a coding agent, a CI job, an MCP server, a script. It carries its own scopes, its own expiry and its own read budget, and it can be revoked without touching the person who made it.

Why an agent is not a user

A personal credential inherits everything its owner can reach. In a secret manager that is usually every project in the organization, which is more authority than something running unattended should hold. If an agent works on your login, a mistake or a prompt injection in that agent has your reach.

A machine identity instead says exactly what it may do: "use the API keys of acme-api in dev", and nothing else. Every read it makes is recorded against the identity, not against you, so the audit trail can tell an agent's reads apart from yours.

The token

The token starts with evl_, distinct from the oat_ tokens issued to people, so a leaked one is recognizable on sight and by secret scanners. Only a hash is stored on the server; the token is shown once, when it is created.

The CLI uses it when it is in ENVEIL_TOKEN, which wins over a keychain login. The HTTP API and the MCP endpoint take it as Authorization: Bearer evl_… or X-API-Key: evl_….

Scopes

A scope is three things:

  • a project,
  • optionally one environment in it. Without one, the scope covers every environment of the project, including environments created later. Narrow production to its environment.
  • a capability: proxy, read or write.

Capabilities are ordered: write includes read, and read includes proxy.

Capability Allows
proxy Using secrets through proxy mode on their allowed hosts, and seeing which keys those are. No values, no export, no history, no writes. enveil list needs read.
read The above, plus listing keys, reading values, exporting an environment, and history
write The above, plus setting and rolling back values

Scopes only add. An identity may do something if any of its scopes allows it, and there is no deny rule. A few settings apply to a whole project, such as a secret's allowed hosts or its expiry, and need write on a scope without an environment: a grant on dev must not change how prod is used.

Prefer proxy. An agent with a proxy-only identity can call the APIs it needs and cannot print the keys it calls them with.

Protected environments do not change what an identity may do. Protection keeps members' logins away from production values; an identity reaches only what its scopes name, and only an admin can grant those. That makes an identity scoped to prod the way to give a job or an agent production access without making its operator an admin.

Expiry and revocation

An identity can expire, given as 30d, 12w, 1y or an RFC 3339 time. Without an expiry it lasts until revoked; agent credentials are meant to be short-lived, so set one.

Revoking an identity stops its token on the next request, because every request checks whether the identity is live before it looks at the scopes. Revocation does not affect the person who created it, or any other identity.

Who may mint one

Only a person, with the owner or admin role in the organization:

  • in the dashboard, on the Identities page, which also sets an expiry and an optional read budget;
  • or with the CLI, logged in as yourself:
sh
enveil identity create --name claude-code --scope acme-api:dev \
  --capability proxy --expires 30d --budget 60/600
enveil identity revoke <id>

--scope is project or project:environment and repeats; --capability applies to all of them. Only the token goes to stdout, so ENVEIL_TOKEN=$(enveil identity create …) captures it, and the id, scopes and expiry go to stderr. --budget is reads per minute and per hour; without it the identity gets the defaults, 600 a minute and 5,000 an hour.

A request made with a machine token to create or revoke an identity is refused with 403. An identity that could mint identities could grant itself more access, or revoke the people who would revoke it.

What it can see

enveil whoami (or the whoami MCP tool) shows what a credential is. For a machine identity:

text
machine identity claude-code (…)
via: machine_identity
org: Acme (…)
scope: proxy acme-api/dev
expires: 2026-11-07T09:12:44+00:00
read limit: 60/minute, 600/hour

An environment shown as * means every environment in the project. --json prints the same as one JSON document.

A machine identity only sees projects it holds a scope on. Others are reported as not found, exactly like a project that does not exist, so an agent cannot map the organization by guessing names.

Identities for CI

GitHub Actions needs no stored token: a trust policy exchanges the job's OIDC token for an identity that expires in minutes. See GitHub Actions.