Store and use a secret

Your tools need credentials, and those credentials should never sit in your tool configuration in plain text. A secret holds the value once. You reference it in a tool header as ${NAME}, and Cadenya swaps in the real value when it calls the tool. The value never comes back out through the API. In this lesson you store an API token as a workspace secret and wire it into a tool set.

What you need

A workspace, with your API key in CADENYA_API_KEY and your workspace ID in WORKSPACE_ID.
A credential to store, such as a third-party API token.

Step 1: Store the secret

In the sidebar, open Secrets and create one. Give it a Name and a Value. Cadenya uppercases the name and turns spaces and hyphens into underscores to form the reference, so stripe_api_key becomes ${STRIPE_API_KEY} and billing-key becomes ${BILLING_KEY}. Stick to letters, digits, and underscores so the reference reads exactly like the name you typed.

The Create secret form with a Name field and a Value field — The Create secret form with a name and a value

The same step from your terminal:

curl https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/workspace_secrets \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "metadata": { "name": "stripe_api_key" },
        "spec": { "value": "sk_live_replace_me" }
      }'

See Create a workspace secret for the full request.

Cadenya stores the value encrypted and never returns it on a read. A response carries the name and labels, never the value. Lose track of a secret and you rotate it, you do not read it back.

Step 2: Reference it in a tool header

A workspace secret is reachable by any tool set in the workspace. Put the reference in the adapter’s headers, where the provider expects the credential:

curl https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/tool_sets \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "metadata": { "name": "Billing", "externalId": "billing" },
        "spec": { "adapter": { "type": "http", "http": {
          "baseUrl": "https://api.stripe.com",
          "headers": { "Authorization": "Bearer ${STRIPE_API_KEY}" }
        } } }
      }'

See Create a tool set for the full request. Cadenya leaves the ${STRIPE_API_KEY} text in the configuration. The substitution happens later, at the moment of the call. The same ${NAME} reference works in MCP and OpenAPI adapter headers, not only HTTP.

Step 3: Watch it resolve at call time

Assign the tool set to an agent and run an objective that calls one of its tools. When the agent fires the call, Cadenya resolves ${STRIPE_API_KEY} against your secrets and sends the real token in the header. The objective’s events show the tool call, but never the secret value. Cadenya catches a missing secret when you connect the tool set, not in production. Sync an MCP or OpenAPI tool set whose header references a name that does not exist and the sync fails with an unresolved_secrets error that names the missing ${NAME}, so a typo surfaces at setup.

Rotate a secret

Rotate by updating the value and keeping the name. Every ${NAME} reference picks up the new value on the next call, so nothing else changes. Pass the secret id from the create response.

curl -X PATCH https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/workspace_secrets/$SECRET_ID \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "value": "sk_live_rotated" }, "updateMask": "spec.value" }'

The old value stops working the moment the update lands, so cut over any caller that holds it. See Update a workspace secret for the full request.

Per-run secrets

A workspace secret is shared across the workspace, which suits a long-lived service token. For a credential scoped to one run, such as a single customer’s short-lived token, pass an objective secret when you start the objective. An objective secret overrides a secret of the same name at any wider scope, so the same ${NAME} reference resolves to the per-run value. There are three scopes, and the narrowest wins: an objective secret, then a tool set secret, then a workspace secret. To see which one a tool call used, read the call by ID and check resolvedSecrets, which names the key and its source without ever revealing the value.

What you built

You stored a credential once, referenced it by name in a tool header, and let Cadenya inject it at call time without ever exposing it. Add more secrets and reference each one the same way.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Store and use a secret

What you need

Step 1: Store the secret

Step 2: Reference it in a tool header

Step 3: Watch it resolve at call time

Rotate a secret

Per-run secrets

What you built

Going further

How secrets work

Connect a tool set

​What you need

​Step 1: Store the secret

​Step 2: Reference it in a tool header

​Step 3: Watch it resolve at call time

​Rotate a secret

​Per-run secrets

​What you built

​Going further

How secrets work

Connect a tool set

What you need

Step 1: Store the secret

Step 2: Reference it in a tool header

Step 3: Watch it resolve at call time

Rotate a secret

Per-run secrets

What you built

Going further