API reference · Management plane

Shared secrets

A key you set once for the whole account — an Anthropic or Stripe key, say. Every function of every project reads it as env.NAME, including projects created later. A project's own secrets are on the Functions page; a project secret masks the shared secret of the same name.

The value passes through one channel: the dashboard, under a signed-in human. No tool exposes these routes, and no route ever returns a value. Your agent reads the names — and the note you write for it — through list_secrets, project by project.

All five routes take an account key of full scope. A key limited to some projects gets 403: they act on the whole account. The four writes also need a signed-in human (X-Account-Session).

GET/v1/account/secrets

The account's shared secrets, sorted by name — never a value. Each carries name, note, updated_at, allow_restricted_keys, generation, application (complete, functions_done, functions_left), masked_in (the projects where a project secret masks it) and reach (what a new value would reach). digest (the SHA-256 of the value) appears only with a signed-in human. removals lists the removals still in progress. Works on the key alone: an agent can see what is left to apply, never apply it

PUT/v1/account/secrets/:name {value, note?, allow_restricted_keys?}

Set or replace. Needs a signed-in human. Writes the registry first, then starts the first wave. A missing field is left unchanged on a replacement; allow_restricted_keys is false at creation. A NEW name that would give a project more than 126 names is refused with 413 before anything is written; replacing a value is never refused

PATCH/v1/account/secrets/:name {note?, allow_restricted_keys?}

Change the note, or close the secret to agent keys limited to some projects. Needs a signed-in human. allow_restricted_keys only accepts false here — reopening goes through PUT, so through the value typed again. Closing starts a wave that takes the value off the functions those keys deployed

DELETE/v1/account/secrets/:name

Remove. Needs a signed-in human — an agent does not remove a key you set for all your projects. The registry first, then the first removal wave; the response carries already_gone. Replaying answers already_gone: true without a wave

POST/v1/account/secrets/:name/apply {generation}

Apply the rest: resumes the named generation at the first function not yet done. Needs a signed-in human. 409 when a wave is already in flight on that name, or when the generation no longer applies; 429 with Retry-After when no call can go out. Idempotent on Idempotency-Key

What a write answers#

The four writes share one shape: 200 with name, generation, application (complete, functions_done, functions_left) and functions: [{project_id, slug, applied, reason}] — what the wave did. When it stopped early, or could not start, it also carries stopped. DELETE adds already_gone.

A value reaches the functions already running a few at a time: one request sends at most 20 administration calls to our infrastructure provider, and stops at the first of its bounds — those 20 calls, a spent budget (stopped: budget), a clock deadline (stopped: deadline), or the provider being busy (stopped: platform_busy). The registry is written either way. Call Apply the rest until application.complete is true.

A function that did not get the value carries its reason: capacity (it would hold too many variables), plain_text_var (it already has a vars entry of that name), refused (another refusal from the provider) — three that no replay repairs, and that its next deployment picks up — or retry (a passing failure).

What does not happen#

A shared secret never reaches another account's project: the registry is keyed by account, and a row only decrypts under its own account.

Removing a shared secret is followed through to the last function: a redeployment that leaves a secret out does not remove it, so the product takes it off script by script. Until the last one has lost it, the secret stays under removals.

Bounds are on the limits page. The screen that types the values is Secrets.