Secrets
Manage encrypted secrets and serve them to in-flight executions.
Secrets in Flux are stored AES-encrypted in the configured database, keyed by a name. All operator routes live under /admin/secrets — the older /secrets prefix has been removed. Workers fetch secrets via a separate per-worker route that enforces the workflow’s declared secret_requests.
Encryption requires [flux.security.encryption].encryption_key to be set; with it unset, every read/write returns 500.
GET /admin/secrets
List all secret names. Values are never returned by list.
- Permission:
admin:secrets:read. - Response:
["KEY_A", "KEY_B", ...].
POST /admin/secrets
Create or update a secret.
- Body (
SecretRequest):{"name": "<KEY>", "value": "<value>"}. - Permission:
admin:secrets:manage. - Response:
{"status": "success", "message": "Secret '<KEY>' saved successfully"}.
GET /admin/secrets/{name}
Get one secret’s plaintext value.
- Permission:
admin:secrets:read. - Response:
{"name": "<KEY>", "value": "<value>"}. - 404: secret not found.
DELETE /admin/secrets/{name}
Remove a secret.
- Permission:
admin:secrets:manage. - Response:
{"status": "success", "message": "Secret '<KEY>' deleted successfully"}.
POST /admin/secrets/batch
Fetch multiple secret values in one round trip.
- Body: list of key names, e.g.
["KEY_A", "KEY_B"]. - Permission:
admin:secrets:read. - Response:
{"KEY_A": "value", "KEY_B": "value"}. - 404: any requested key is missing from the store.
POST /workers/{name}/secrets/batch
Worker-only. The worker fetches secrets needed by an in-flight execution. The server enforces that every requested key is listed in the workflow’s metadata.secret_requests; any undeclared key causes a 403 that names the disallowed keys.
- Body:
{"execution_id": "<id>", "names": ["KEY_A", "KEY_B"]}. - Permission:
worker:*:*; identity must match the path{name}. - Response:
{"KEY_A": "value", ...}. - 403: worker does not own the execution, or requested keys are not declared on the workflow.
See Workers for the rest of the worker-side surface.
Permission model
Two permissions cover the operator surface:
| Permission | Grants |
|---|---|
admin:secrets:read | List names, get values, batch-get values. |
admin:secrets:manage | Create, update, delete. |
The built-in admin role holds both via the * wildcard. The built-in operator and viewer roles do not — granting secret access to non-admin principals requires a custom role or an explicit per-permission grant.
Worker secret fetches are gated separately by worker:*:* plus the per-execution ownership check; granting admin:secrets:read to a worker is not required and not recommended.
Encryption
Secret values are encrypted with AES via PyCryptodome before being written to the database. The encryption key is set via [flux.security.encryption].encryption_key or the FLUX_SECURITY__ENCRYPTION__ENCRYPTION_KEY environment variable. With this unset, every secret read/write raises a 500 — Flux no longer ships a default key, and as of 0.56.0 a server with auth enabled refuses to start until one is set.
Rotating the encryption key requires re-encrypting existing secrets: there is no built-in migration command, so plan to re-set every secret manually if you rotate.
CLI alternative
For interactive use, flux secrets set|get|list|remove wraps these endpoints. The REST API is what you want for automation, CI provisioning, and any flow that needs to hand a secret to a workflow programmatically.