Secret providers
A linked secret keeps a reference to a value held by an external provider instead of the value itself. Falak resolves it on the control plane when a deployment (or a build) needs it, so the value never has to be copied into Falak by hand.
Add a provider
Section titled “Add a provider”- Open Settings → Secret providers → Add (
secrets.providers.manage, owners and admins). - Pick the type and fill in its settings (below). Credentials are write-only: they are sealed at rest and never shown again.
- Optionally set the cache TTL (default 5 minutes, 0 always asks the provider).
- Save, then Test connection. The provider’s status turns OK or Failing with the reason.
Then create a secret on any Secrets page with Source: Linked to a provider, pick the provider and enter the reference.
Providers and references
Section titled “Providers and references”| Provider | Reference |
|---|---|
| HashiCorp Vault / OpenBao | vault://<mount>/data/<path>#<key> (KV v2) · vault://<mount>/<path>#<key> (KV v1, set on the provider) |
| AWS Secrets Manager | aws-sm://<name or ARN> · aws-sm://<name>#<json key> (one key of a JSON secret) |
| AWS SSM Parameter Store | aws-ssm:///<path/name> (or aws-ssm://<name>; read with decryption) |
| 1Password | op://<vault>/<item>/<field> · op://<vault>/<item>/<section>/<field> |
| Doppler | doppler://<project>/<config>/<NAME> |
| Infisical | infisical://<project id>/<environment>[/<path>…]/<NAME> |
| HTTPS webhook | https://<base URL>/<name> |
- A reference must match its provider’s type; Falak checks it when the secret is saved. When the organization has exactly one provider of a reference’s type, you can leave the provider out.
- Values are text. Vault and AWS JSON values pick one key (
#key); numbers and booleans become their JSON text.
| Setting | Notes |
|---|---|
| Address | https://vault.example.com |
| Namespace | Optional (Vault Enterprise / HCP) |
| KV version | 2 (default) or 1 |
| Auth method | Token; AppRole (role id + secret id); JWT / OIDC (role + JWT). Optional auth mount |
| CA certificate | Optional, for a private CA |
Logins (AppRole and JWT client tokens) are cached sealed until shortly before they expire.
One provider type each for Secrets Manager and SSM Parameter Store.
| Setting | Notes |
|---|---|
| Region | e.g. eu-central-1 |
| Auth | Access key id + secret access key (+ session token), optionally an STS AssumeRole (role ARN, external id) |
Instance profile. When the control plane runs on EC2, the operator can let AWS providers use its own role (IMDSv2) with FALAK_SECRETS_PROVIDERS_ALLOW_INSTANCE_PROFILE=true (off by default). The instance profile is then only ever used to assume a role of the organization’s (the role ARN is required), and the external ID sent is always the organization’s id. Pin it in the role’s trust policy, so no other organization of the instance can assume the role:
{"Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::<control plane account>:role/<control plane role>"}, "Action": "sts:AssumeRole", "Condition": {"StringEquals": {"sts:ExternalId": "<your organization id>"}}}| Setting | Notes |
|---|---|
| Connect URL | Your 1Password Connect server |
| Token | A Connect token |
| CA certificate | Optional |
Service account tokens only work through 1Password’s SDKs and CLI, so run a Connect server (it can use the same vaults). Lookups must be unambiguous: two vaults, items or fields with the same name (and no section to tell fields apart) are an error, as is an empty field.
| Setting | Notes |
|---|---|
| Token | A Doppler service token |
| Setting | Notes |
|---|---|
| Base URL | Infisical Cloud or your self-hosted URL |
| Client id, client secret | A machine identity with universal auth |
| CA certificate | Optional |
For anything without a native driver: an internal secrets service, or a small adapter in front of another vault (the same model as External Secrets’ webhook provider).
| Setting | Notes |
|---|---|
| Base URL | https://secrets.internal.example.com/v1 |
| Header | Optional auth header, e.g. Authorization: Bearer … or X-Api-Key: … |
| CA certificate | Optional |
The contract:
GET {base URL}?ref=<name><header>: <value> (when configured)Accept: application/json
200 {"value": "the secret value"}<name>is everything after the base URL in the reference, sent asref. The header is only ever sent to the base URL.- Any non-2xx answer is a failure (
404reads as “not found”,401/403as “access refused”).valuemust be a string, number or boolean. Redirects are not followed. - Test connection asks for
ref=__falak_connection_test__: any2xxor404passes,401/403fails.
Caching and outages
Section titled “Caching and outages”-
A resolved value is cached sealed in the database, bound to its provider and reference. Within the cache TTL, deployments use it without calling the provider.
-
After the TTL the provider is asked again. If it fails, the last good value is used, the provider turns Failing, and
secrets.provider_unreachablefires (once, untilsecrets.provider_recovered). -
The last good value is used for at most 24 hours after it was fetched (
FALAK_SECRETS_PROVIDERS_MAX_STALE_SECONDS). Past that, or with nothing cached, deployments fail with the reason — never with credentials, values or the provider’s response body:secret DB_PASS: Production Vault: HashiCorp Vault / OpenBao at vault.example.com is unreachable … -
Values larger than 64 KiB are refused.
-
Changing a provider’s settings drops its cached values and logins.
Watching for changes
Section titled “Watching for changes”A linked secret can be watched: set Watch every (minutes, at least 1) when you create or edit it. Falak asks the provider at that interval and compares the answer with the last value it saw (only an HMAC of it is kept). On a change, Falak:
- records a new version (same reference, note Changed upstream) holding the new value as a sealed snapshot;
- fires
secrets.linked_changed(names only); - does what When it changes says: nothing more, restart the processes of the services that use it, or redeploy them.
A value reaches a service’s environment when it is deployed, so choose redeploy for environment variables; restart suits apps that read the secret from the provider themselves when they boot.
Rolling back a linked secret
Section titled “Rolling back a linked secret”Each version keeps its reference and, when the watch saw it, the value it had. Rolling back to such a version pins the secret to that value: deployments use the snapshot instead of asking the provider, and the watch pauses. Saving the reference again (a new version) unpins it. Rolling back to a version without a snapshot only restores its reference.
Network safety
Section titled “Network safety”- Endpoints must be
https://, and TLS is always verified (add a CA certificate for a private CA). Timeouts: 5 s to connect, 10 s in total, one retry. - Endpoints must resolve to public addresses. A provider on a private network needs both the instance setting
FALAK_SECRETS_PROVIDERS_ALLOW_PRIVATE=true(operator, off by default) and the provider’s Allow private network (Vault, OpenBao, Infisical, 1Password Connect and webhooks). - Link-local and cloud metadata addresses are always refused. The check runs when the provider is saved and before every request, and the request is pinned to the addresses checked.
Permissions
Section titled “Permissions”secrets.view sees providers (names, types, status, non-secret settings). secrets.providers.manage (owners and admins) adds, edits, tests and deletes them — whoever edits an endpoint decides where credentials are sent, so changing a URL, CA certificate, namespace, region, role, external ID or webhook header requires entering every credential again. Developers link secrets to existing providers with secrets.manage. A provider used by linked secrets can’t be deleted.