Secrets API
Organization secrets in four scopes (organization, project, environment, service — a project service id), referenced from variables as ${{ secrets.NAME }}. See Secret store.
Names match ^[A-Z_][A-Z0-9_]*$ and are unique per scope. Responses carry metadata only: id, name, scope, scope_id, scope_label, kind, sensitive, available_to_previews, description, rotation_days, rotation_due_at, current_version, last_accessed_at, created_at, updated_at, plus for linked secrets provider_id, watch_minutes, on_change, last_polled_at. Secrets of other organizations are 404.
GET /api/v1/secrets[?scope=&scope_id=] · GET /api/v1/secrets/{secret} — secrets.view
Section titled “GET /api/v1/secrets[?scope=&scope_id=] · GET /api/v1/secrets/{secret} — secrets.view”POST /api/v1/secrets — secrets.manage
Section titled “POST /api/v1/secrets — secrets.manage”{"name": "STRIPE_SECRET", "scope": "project", "scope_id": "01k…", "value": "sk_live_…", "sensitive": true, "available_to_previews": false, "description": "Stripe live key", "rotation_days": 90}A linked secret takes "kind": "linked", "reference": "vault://kv/data/app#STRIPE", "provider_id": "01k…" instead of value; watch_minutes (1–1440, null: not watched) and on_change (none, restart or redeploy) set the watch. Without provider_id, the organization’s only provider of the reference’s type is used. sensitive defaults to true, available_to_previews to false. 201.
A sensitive secret is write-only: it can be replaced, never revealed, and stays sensitive.
PUT /api/v1/secrets/{secret}/value — secrets.manage
Section titled “PUT /api/v1/secrets/{secret}/value — secrets.manage”{"value": "…"}: a new version, current from the next deployment.
POST /api/v1/secrets/{secret}/rollback — secrets.manage
Section titled “POST /api/v1/secrets/{secret}/rollback — secrets.manage”{"version": 3}: a new version with that version’s value (history is never rewritten). Disabled versions can’t be restored. A linked version that recorded its value upstream is restored pinned to that value until a new reference is saved.
DELETE /api/v1/secrets/{secret} — secrets.manage
Section titled “DELETE /api/v1/secrets/{secret} — secrets.manage”Every version goes; the access log stays. References to it fail the next deployment.
POST /api/v1/secrets/{secret}/reveal[?version=] — secrets.reveal
Section titled “POST /api/v1/secrets/{secret}/reveal[?version=] — secrets.reveal”{"data": {"version": 3, "value": "…"}} (a linked secret: its reference). 403 for sensitive secrets, and for tokens without the secrets.reveal ability by name (* is not enough). Logged in the access log as the token, and audited.
Providers
Section titled “Providers”Responses never carry credentials:
{"id": "01k…", "name": "Production Vault", "type": "vault", "type_label": "HashiCorp Vault / OpenBao", "scheme": "vault", "settings": {"address": "https://vault.example.com", "kv_version": "2", "auth_method": "approle", "role_id": "…"}, "stored_credentials": ["secret_id"], "allow_private_network": false, "cache_ttl_seconds": 300, "status": "untested|ok|error", "last_checked_at": "…", "last_error": null, "secrets_count": 3, "created_at": "…", "updated_at": "…"}GET /api/v1/secrets/providers · GET /api/v1/secrets/providers/{provider} — secrets.view
Section titled “GET /api/v1/secrets/providers · GET /api/v1/secrets/providers/{provider} — secrets.view”POST /api/v1/secrets/providers — secrets.providers.manage
Section titled “POST /api/v1/secrets/providers — secrets.providers.manage”{name, type, config, allow_private_network?, cache_ttl_seconds?} (cache TTL 0–86400, default 300). type and its config:
type |
config |
|---|---|
vault |
address, namespace?, kv_version (2|1), auth_method (approle|token|jwt), token | role_id + secret_id | role + jwt, auth_mount?, ca_pem? |
aws_secrets_manager, aws_ssm |
region, auth_method (keys|instance_profile), access_key_id, secret_access_key, session_token?, role_arn?, external_id? |
onepassword |
connect_url, token, ca_pem? |
doppler |
token |
infisical |
base_url, client_id, client_secret, ca_pem? |
http |
base_url, header_name?, header_value?, ca_pem? |
URLs are https:// and must resolve to public addresses unless allow_private_network (self-hostable types only, and only when the instance sets FALAK_SECRETS_PROVIDERS_ALLOW_PRIVATE=true). With auth_method: instance_profile, role_arn is required and the external ID is always the organization id.
PATCH /api/v1/secrets/providers/{provider} — secrets.providers.manage
Section titled “PATCH /api/v1/secrets/providers/{provider} — secrets.providers.manage”Same fields but type; without config the settings stay as they are. Credentials left empty keep their stored value, unless a setting that decides where they are sent (URL, CA, namespace, region, role, external ID, header) changes: then every credential must be sent again (422 otherwise). Changing settings resets the status to untested and drops the cached values.
POST /api/v1/secrets/providers/{provider}/test — secrets.providers.manage
Section titled “POST /api/v1/secrets/providers/{provider}/test — secrets.providers.manage”Checks the endpoint and credentials and records the status. 422 {"errors": {"provider": ["…"]}} when it fails.
DELETE /api/v1/secrets/providers/{provider} — secrets.providers.manage
Section titled “DELETE /api/v1/secrets/providers/{provider} — secrets.providers.manage”422 while linked secrets use it. Its cached values are deleted.