HTTP API

The token API used by the CLI, CI and scripts

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:

http
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:

json
{
  "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.

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.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" https://enveil.oxidt.com/api/v1/whoami
json
{
  "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.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" https://enveil.oxidt.com/api/v1/projects
json
[{ "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
bash
curl -X POST -H "Authorization: Bearer $ENVEIL_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Acme API"}' https://enveil.oxidt.com/api/v1/projects

Returns 201 with the same shape as a list entry.

GET /api/v1/projects/{project}/environments

Environments of a project the caller can see.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
  https://enveil.oxidt.com/api/v1/projects/acme-api/environments
json
[
  { "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.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
  https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets
json
[{ "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.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
  https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/export > .env

GET …/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.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
  https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets/STRIPE_SECRET_KEY
json
{ "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.
bash
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
json
{ "version": 4 }

PUT on a linked key is refused with 409 conflict naming the source; change the value there.

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.
bash
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/link

DELETE …/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.

bash
curl -X DELETE -H "Authorization: Bearer $ENVEIL_TOKEN" \
  https://enveil.oxidt.com/api/v1/projects/acme-api/environments/dev/secrets/OLD_KEY

PUT /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
bash
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-hosts

See 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.

bash
curl -H "Authorization: Bearer $ENVEIL_TOKEN" \
  https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/secrets/STRIPE_SECRET_KEY/versions
json
[
  { "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.

json
{ "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
bash
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
json
{ "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.
bash
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/identities

Returns 201:

json
{ "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.

bash
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).

bash
curl -X POST -H "Content-Type: application/json" \
  -d "{\"token\": \"$ACTIONS_OIDC_TOKEN\", \"org\": \"acme\"}" \
  https://enveil.oxidt.com/api/v1/oidc/token
json
{ "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 /mcp as 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.