REST API

Everything the CLI does goes through the REST API under /api/v0, and the API Reference tab above documents every route. Its OpenAPI description is at /api/v0/openapi.json on your instance.

Authentication

Send an API or machine token as a bearer token:

1curl -H "Authorization: Bearer sig_xxx" https://<your-instance>/api/v0/me

A token reaches only its project, and only the environments it's scoped to. Reading or changing a protected environment takes a machine token. A workload gets a token for its JWT from POST /api/v0/workload/token: see workload identity.

Examples

12345678910111213141516171819# list secrets
curl -H "Authorization: Bearer sig_xxx" \
  https://<your-instance>/api/v0/projects/{projectId}/environments/{environmentId}/secrets

# set a secret
curl -X POST -H "Authorization: Bearer sig_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "API_KEY", "value": "sk-live-xxx"}' \
  https://<your-instance>/api/v0/projects/{projectId}/environments/{environmentId}/secrets

# bulk download as JSON
curl -H "Authorization: Bearer sig_xxx" \
  https://<your-instance>/api/v0/projects/{projectId}/environments/{environmentId}/secrets/download?format=json

# bulk set
curl -X PUT -H "Authorization: Bearer sig_xxx" \
  -H "Content-Type: application/json" \
  -d '{"secrets": {"KEY1": "val1", "KEY2": "val2"}}' \
  https://<your-instance>/api/v0/projects/{projectId}/environments/{environmentId}/secrets

{environmentId} also takes the environment's slug. The download takes the same formats as sigillo secrets download, but defaults to JSON.

Expiry headers

Every response to a request with a sig_ token that expires says when, in RFC 3339. For a workload's token it's the trust rule's expiry, since the workload gets a new token every hour on its own. In the last quarter of the credential's lifetime, and at most its last 14 days, a second header warns:

12Sigillo-Token-Expires: 2026-10-13T12:00:00Z
Sigillo-Warning: token-expiry; expires=2026-10-13T12:00:00Z; days=3

The kinds are token-expiry, rule-expiry (with rule=<id>), and token-regenerated, which the old value of a regenerated token gets during its grace. days rounds up. The CLI prints the warning on stderr. POST /api/v0/workload/token also answers the rule's ruleId and ruleExpiresAt.

Doppler-compatible routes

For External Secrets Operator's Doppler provider, the instance also answers three of Doppler's routes, at its root rather than under /api/v0: POST /v3/auth/oidc, GET /v3/projects and GET /v3/configs/config/secrets/download. They take the token as Basic auth user name, as that provider sends it, and answer in Doppler's shape. They exist for ESO; use /api/v0 for anything else.