Skip to main content
POST
JavaScript
A secret is a value your agents need and you never want back. Store it here, reference it by name in a tool set adapter’s headers, and Cadenya substitutes it at call time.
Then reference it wherever an adapter takes headers:

The value is write-only

spec.value never comes back. Not on read, not even on the create response, which returns {"value": ""}. There is no endpoint that reveals a stored secret. The name doubles as the external ID: create DEMO_TOKEN and metadata.externalId is set to DEMO_TOKEN for you. Names are unique within a workspace, so a second DEMO_TOKEN is a 409. Rotate by updating the value in place, with a field mask:

Three scopes, narrowest wins

The same name can exist at three levels. When a tool call resolves ${DEMO_TOKEN}, Cadenya checks them in order and the first hit wins. That ordering is what makes per-user credentials work. The workspace holds your service account. The objective carries the token of whoever is asking. The same tool, the same header, a different identity per run.

Prove which one won

You never see a secret’s value, but you can always see which scope supplied it. Read the tool call and resolvedSecrets names the key and its source.
Running the same agent three times, adding one scope each time, shows the shadowing directly:
resolvedSecrets appears on the tool call detail view, not on items from the tool calls list. Fetch the call by ID.
This is the tool to reach for when an agent authenticates as the wrong identity. The header looks right and the value is invisible, so the source field is the only evidence you get.

Interpolation rules

${NAME} is substituted into adapter headers at call time, and for an HTTP tool also into the path, query, and request body template. The value never enters the model’s context, and it is not written to the event timeline. A reference that resolves to nothing is not silently blank. A tool set whose adapter names a secret that does not exist fails its sync with an unresolved_secrets error, so a typo surfaces when you create the tool set rather than when an agent calls it.
Never inline a real credential in an adapter header. It would be stored in the tool set spec, which is returned on read. Always use a ${NAME} reference.

Store and use secrets

The hands-on lesson, from secret to authenticated tool call.

Create a tool set

Where ${NAME} gets referenced, and tool-set-scoped secrets live.

Create an objective

Per-run secrets, for short-lived per-user tokens.

Secrets

How resolution works, and what never leaves the vault.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

The workspace that will own this secret.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json
metadata
object
required

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

spec
object
required

Response

OK

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

spec
object
required
info
object

Workspace secret information