Secrets

The values an agent workflow references as ${{secrets.KEY}}. Six tools.

The value is write-only. No tool returns it — not even to the client that just wrote it. If the user will need the credential elsewhere, show it to them before storing it.

See the Secret model.

---

secrets_list

Read · scope inbox/secrets · permission secrets.list · GET /secrets

List the workspace secrets. The response carries key, notes, last_used_at and timestamps only.

Parameter	Type	Description
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
key	string	Filter by key.

secrets_get

Read · scope inbox/secrets · permission secrets.show · GET /secrets/{id}

Fetch one secret by id. The value is not part of the response.

Parameter	Type	Description
id required	string (uuid)	Secret id.

secrets_create

Write · scope inbox/secrets + write · permission secrets.create · POST /secrets

Store a new secret. A duplicate key in the workspace is refused with 409 conflict.

Parameter	Type	Description
key required	string	Uppercase letters, digits and underscores, starting with a letter — what a step writes inside ${{secrets.KEY}}.
value required	string	Stored encrypted; never returned.
notes	string | null	What the value is for.
idempotency_key	string	Replay guard.

secrets_upsert

Write · scope inbox/secrets + write · permission secrets.create · PUT /secrets

Create the secret, or replace the value of the existing one with the same key. The rotation path: no id lookup first.

Parameter	Type	Description
key required	string	Lookup key of the upsert.
value required	string	Replaces the stored value.
notes	string | null
idempotency_key	string	Replay guard.

secrets_update

Write · scope inbox/secrets + write · permission secrets.update · PATCH /secrets/{id}

Replace a secret value or its notes. key is immutable — workflows reference it by name, so renaming it would break them silently.

Parameter	Type	Description
id required	string (uuid)	Secret id.
value	string	New value.
notes	string | null

secrets_delete

Write · scope inbox/secrets + write · permission secrets.delete · DELETE /secrets/{id}

Soft-delete a secret. From the next run on, any step referencing its key fails with secret not defined, before the request is sent.

Parameter	Type	Description
id required	string (uuid)	Secret id.