JavaScript
Workspace Secrets
Create a workspace secret
Store a credential once, reference it as $ in adapter headers, and never see it in a response again.
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:
Running the same agent three times, adding one scope each time, shows the shadowing directly:
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.
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 andresolvedSecrets names the key and its source.
resolvedSecrets appears on the tool call detail view, not on items from the tool calls list. Fetch the call by ID.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.
Related
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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The workspace that will own this secret.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
application/json