The token API is what the CLI and CI use. Anything enveil does, a script can do over plain HTTP. Every response is JSON except the .env export, which is text/plain so curl … > .env does the obvious thing.
The examples use https://enveil.oxidt.com. Replace it with your own server if you self-host. All paths are under /api/v1.
Authentication
Send the credential in either header:
Authorization: Bearer <token>
X-API-Key: <token>Which credential you send decides what the call can reach:
| Credential | Looks like | Reach |
|---|---|---|
| Machine identity | evl_… |
Only the projects and environments in its scope list, at the capability each grants. See Machine identities. |
A person's key from enveil login |
oat_… |
Everything that person's organization role allows. The key was granted the api scope; a key granted only mcp (an MCP connector's) is refused here with 403. |
| A person's key created in the dashboard | oat_… |
Same as above, unscoped. |
| GitHub Actions OIDC token | a JWT | Not accepted directly. Trade it at the OIDC exchange for a short-lived evl_… identity. |
A person's key acts in the organization it was minted in; the request cannot pick another. Machine identities act in the organization of the member who created them, and stop working if that member leaves.
Capabilities are ordered: write includes read, and read includes proxy. A proxy scope can be used through enveil run --proxy but cannot read, export, list history or write.
Errors
Errors are JSON with an error message. Most also carry a stable reason and a retryable flag:
{
"error": "Read budget exceeded: This credential has read 601 secrets in the last minute, over its limit of 600. …",
"reason": "read_budget_exceeded",
"retryable": true
}Branch on reason, never on error; the message is for people and may change. A few refusals, such as a missing credential or a machine identity calling a people-only route, carry only error.
| Status | reason |
Meaning |
|---|---|---|
400 |
validation_failed |
A malformed field: a bad key name, an unknown host, an expiry in the past. |
401 |
unauthorized |
No credential, an invalid or revoked one, or a credential whose scope or role does not allow this action on a project it can see. |
403 |
— | The credential is valid but this route is not for it: a machine identity creating projects or identities, or a key without the api scope. |
403 |
forbidden |
A person with the Member role reading or changing values in a protected environment: Production is protected: only admins can read or change its values. |
404 |
not_found |
The project, environment, key or version does not exist or is outside the caller's scope. |
409 |
conflict |
Something with that name already exists. |
429 |
read_budget_exceeded |
The credential has read more secrets than its per-minute or per-hour budget. Wait, then retry. |
429 |
— | Too many requests from one IP: 120 per minute on the API, 20 per minute on the OIDC exchange. This one answers with a plain-text body, not JSON. |
500 |
internal_error |
A server fault. Details go to the server log, not the response. |
A project outside a machine identity's scope answers 404, not 403. A narrowly scoped agent cannot tell which other projects exist, so it cannot learn what the organization is building or which vendors it uses by probing names.
rate_limit_exceeded is the reason other enveil surfaces (MCP, the dashboard) use for their own limits; on the token API the per-IP limit is the plain-text 429 above.
Reads, disclosure and the audit trail
Some calls return secret values. Those are recorded in the audit trail against the credential that asked, and charged to its read budget, one unit per secret disclosed. An export of 40 secrets costs 40. Calls that return only metadata are neither recorded nor metered. Writes are always recorded. See Audit and read budgets.
| Route | Discloses values | Recorded |
|---|---|---|
GET …/secrets/{key} |
yes | yes, metered |
GET …/versions/{version} |
yes | yes, metered |
GET …/export |
yes | yes, metered per secret |
GET …/manifest |
yes | yes, metered per secret |
PUT / DELETE …/secrets/{key}, PUT …/link, POST …/rollback, PUT …/proxy-hosts |
no | yes |
POST / DELETE /api/v1/identities |
no | yes |
GET …/secrets, GET …/versions, GET /projects, GET …/environments, GET /whoami |
no | no |
A person's token is metered against the deployment defaults (600 per minute, 5,000 per hour). A person in the browser is not metered.
Identity
GET /api/v1/whoami
Who the credential is and what it may do, so a caller can learn its limits without probing for them. Any credential.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" https://enveil.oxidt.com/api/v1/whoami{
"kind": "machine",
"id": "3f0c…",
"email": null,
"name": "deploy-bot",
"via": "machine_identity",
"oauth_client": null,
"role": null,
"org": { "id": "8a21…", "name": "Acme" },
"scopes": [{ "project": "acme-api", "environment": "prod", "capability": "read" }],
"expires_at": "2026-11-01T00:00:00+00:00",
"read_limits": { "per_minute": 600, "per_hour": 5000 }
}| Field | Meaning |
|---|---|
kind |
user or machine. |
email / name |
A person's email, or a machine identity's name. The other is null. |
via |
api_key (a key you created), oauth (a token an OAuth client such as enveil login obtained), jwt or machine_identity. |
oauth_client |
The OAuth client that obtained a person's key, such as the CLI. |
role |
A person's organization role: Owner, Admin or Member. null for a machine. |
scopes |
A machine identity's grants. environment: null means every environment of the project. null for a person. |
expires_at |
When a machine identity lapses, or null. |
read_limits |
The read budget, or null when reads are not metered. |
Projects and environments
GET /api/v1/projects
Projects the caller can see: all of the organization's for a person, only scoped ones for a machine identity.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" https://enveil.oxidt.com/api/v1/projects[{ "slug": "acme-api", "name": "Acme API", "description": null }]POST /api/v1/projects
Create a project. People only, role Member or above: a machine identity is scoped to projects that already exist, and creating new ones would be reach it was not given. The slug is derived from the name; a taken slug gets a numeric suffix. New projects start with dev, staging and prod.
| Field | Type | |
|---|---|---|
name |
string | required |
description |
string | optional |
curl -X POST -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
-d '{"name": "Acme API"}' https://enveil.oxidt.com/api/v1/projectsReturns 201 with the same shape as a list entry.
GET /api/v1/projects/{project}/environments
Environments of a project the caller can see.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments[
{ "slug": "dev", "name": "Development", "protected": false },
{ "slug": "prod", "name": "Production", "protected": true }
]| Field | Type | |
|---|---|---|
slug |
string | Used in paths |
name |
string | Display name |
protected |
boolean | Members can list keys and history but not read or change values. See Protected environments. |
Secrets
Paths below are under /api/v1/projects/{project}/environments/{environment} unless shown in full. Keys must start with a letter or underscore and contain only letters, digits and underscores, up to 255 characters, so they survive a .env file and a process environment.
GET …/secrets
Key names and metadata for the secrets that have a value, or are a link, in this environment. No values. Needs read. A linked key carries link, its source as project/environment:KEY, and the source's proxy hosts, approval and expiry.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets[{ "key": "STRIPE_SECRET_KEY", "note": null, "proxy_hosts": ["api.stripe.com"], "expires_at": null },
{ "key": "SMTP_PASSWORD", "note": null, "proxy_hosts": [], "expires_at": null, "link": "shared/prod:SMTP_PASSWORD" }]Reads of a linked key (export, manifest, secrets/{key}, the proxy) return the source's current value and are recorded against this environment with the source named. A link whose source cannot be read fails the whole export rather than leaving the key out.
GET …/export
Every value in the environment as .env text, quoted where a value would not survive unquoted. Needs read. Discloses values; recorded and metered per secret. This is what enveil pull writes.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/export > .envGET …/manifest
The same values as JSON with each key's proxy hosts: [{ "key", "value", "proxy_hosts" }]. Kept for older CLI clients; current proxy mode does not use it. Needs read. Discloses values; recorded and metered per secret.
GET …/secrets/{key}
One value. Needs read. Discloses the value; recorded and metered.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets/STRIPE_SECRET_KEY{ "key": "STRIPE_SECRET_KEY", "value": "…" }PUT …/secrets/{key}
Create or replace a value in this environment. The previous value is archived as a version, not overwritten. Needs write on the environment and role Member or above. Recorded.
| Field | Type | |
|---|---|---|
value |
string | required |
expires_at |
RFC 3339 timestamp or null |
optional. Absent leaves the expiry alone, null clears it. The expiry belongs to the key in every environment, so setting it needs write on the whole project. |
curl -X PUT -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
-d "{\"value\": \"$NEW_VALUE\"}" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets/STRIPE_SECRET_KEY{ "version": 4 }PUT on a linked key is refused with 409 conflict naming the source; change the value there.
PUT …/secrets/{key}/link
Make the key a link to a value in another project of the organization. Needs write here, read on the source, and a person's credential of an admin or owner: a link lets whoever reads this environment read the source. The source must be a value, not a link. Recorded as secret_linked. Returns 204.
| Field | Type | |
|---|---|---|
project |
string | required, the source project's slug |
environment |
string | optional, defaults to this environment's slug |
key |
string | optional, defaults to this key |
replace |
boolean | optional, default false. If the key holds its own value here, archive it and link in one transaction instead of refusing with 409. The secret_linked event then carries the replaced version. Removing the link keeps that archive, and rollback can restore it. |
curl -X PUT -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
-d '{"project": "shared"}' \
https://enveil.oxidt.com/api/v1/projects/smiet/environments/prod/secrets/SMTP_PASSWORD/linkDELETE …/secrets/{key}
Remove the value in this environment only; write on dev does not reach prod. Needs write and role Member or above. Recorded. Returns 204. On a linked key, removes the link (admin or owner, recorded as secret_unlinked) and leaves the source alone. A value that something links to is refused with 409 conflict, listing the links.
curl -X DELETE -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/dev/secrets/OLD_KEYPUT /api/v1/projects/{project}/secrets/{key}/proxy-hosts
Replace the hosts enveil run --proxy may send this secret to. The list applies in every environment, so it needs write on the whole project; a machine identity scoped to one environment cannot change it. Role Member or above. Recorded, since adding a host widens where a value can go. An empty list removes the secret from proxy mode. Returns 204.
| Field | Type | |
|---|---|---|
hosts |
array of strings | required |
curl -X PUT -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
-d '{"hosts": ["api.stripe.com"]}' \
https://enveil.oxidt.com/api/v1/projects/acme-api/secrets/STRIPE_SECRET_KEY/proxy-hostsSee Proxy mode. The relay itself, GET/POST …/environments/{environment}/proxy, is internal to enveil run --proxy and not meant to be called by hand.
Versions and rollback
See Versions and rollback for why rollback never decrypts.
GET …/secrets/{key}/versions
The history of a value in this environment, newest first. Metadata only. Needs read; not recorded.
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets/STRIPE_SECRET_KEY/versions[
{ "version": 3, "created_at": "2026-10-02T09:14:00+00:00", "actor_kind": "user", "actor_id": "5b7e…", "is_current": true },
{ "version": 2, "created_at": "2026-09-12T16:40:00+00:00", "actor_kind": "machine", "actor_id": "3f0c…", "is_current": false }
]GET …/secrets/{key}/versions/{version}
One historical value. Needs read. Discloses the value; recorded and metered like any read.
{ "key": "STRIPE_SECRET_KEY", "version": 2, "value": "…" }POST …/secrets/{key}/rollback
Copy an archived version forward as a new current version. The ciphertext is copied without decrypting, so nothing is disclosed. Needs write and role Member or above. Recorded. Rolling back to the version that is already current is a 400.
| Field | Type | |
|---|---|---|
version |
integer | required |
curl -X POST -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
-d '{"version": 2}' \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets/STRIPE_SECRET_KEY/rollback{ "version": 4 }Machine identities
Both routes are for people only, role Admin or above. A machine identity that could mint or revoke identities could grant itself more access, or cut off the people who could revoke it, so it gets 403.
POST /api/v1/identities
Mint a machine identity. The token is in this response and nowhere else; the server stores only its hash. Recorded.
| Field | Type | |
|---|---|---|
name |
string | required, 1–64 characters |
scopes |
array | required, at least one: { "project": slug, "environment": slug or omitted, "capability": "proxy" | "read" | "write" }. Omitting environment grants every environment of the project. |
expires_at |
RFC 3339 timestamp | optional, must be in the future. Omitted means the identity does not expire. |
read_budget |
{ "per_minute", "per_hour" } |
optional. Either left out stays on the deployment default. |
curl -X POST -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "deploy-bot",
"scopes": [{ "project": "acme-api", "environment": "prod", "capability": "read" }],
"expires_at": "2026-11-01T00:00:00Z",
"read_budget": { "per_minute": 60 }
}' \
https://enveil.oxidt.com/api/v1/identitiesReturns 201:
{ "token": "evl_…", "id": "3f0c…", "expires_at": "2026-11-01T00:00:00+00:00" }DELETE /api/v1/identities/{id}
Revoke an identity. It stops working at once; the row is kept so the audit trail still names what it did. Recorded. Returns 204.
curl -X DELETE -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/identities/3f0c…OIDC exchange
POST /api/v1/oidc/token
Trade a CI provider's OIDC token for a short-lived machine identity. This is the one route that takes no bearer header: the OIDC token in the body is the credential. Limited to 20 requests per minute per IP.
| Field | Type | |
|---|---|---|
token |
string | required. The OIDC token the provider minted for this run. |
org |
string | required. Slug of the organization whose trust policies apply. |
The token's signature, issuer, audience and expiry are checked, then its subject is matched against that organization's trust policies. Each token can be exchanged once. The identity gets the matching policy's scopes and expires after the policy's lifetime (15 minutes by default, at most an hour).
curl -X POST -H "Content-Type: application/json" \
-d "{\"token\": \"$ACTIONS_OIDC_TOKEN\", \"org\": \"acme\"}" \
https://enveil.oxidt.com/api/v1/oidc/token{ "token": "evl_…", "expires_at": "2026-10-08T12:15:00+00:00", "identity": "9d42…" }Every failure, whether a bad signature, a wrong audience, an unmatched subject or no policy at all, answers the same 401 with "No trust policy accepts this token.". Telling them apart would let a caller map which workflows an organization trusts. The CLI does all of this itself in GitHub Actions; see CI with GitHub Actions.
MCP
/mcp is the Model Context Protocol endpoint. It speaks JSON-RPC and is shaped for a model rather than a script; tool errors carry the same reason and retryable fields. Connect a client to it as described in the MCP guide.
OAuth metadata
MCP clients discover the authorization server from two documents:
GET /.well-known/oauth-protected-resource(also at/.well-known/oauth-protected-resource/mcp) names/mcpas the resource and the server as its authorization server.GET /.well-known/oauth-authorization-server(also at/.well-known/openid-configuration) lists the endpoints:
| Endpoint | Path |
|---|---|
| Authorization | /oauth/authorize |
| Token | /oauth/token |
| Dynamic client registration | /oauth/register |
| Device authorization | /oauth/device_authorization |
| Revocation | /oauth/revoke |
Supported grants are authorization_code (PKCE with S256 required), refresh_token, and the device grant urn:ietf:params:oauth:grant-type:device_code. enveil login uses the same endpoints; enveil login --device uses the device grant where no browser can reach a loopback port. Clients are public; there is no client secret. Access tokens are opaque oat_… keys, not JWTs, so there is no jwks_uri.