Secrets

A secret is a named value stored encrypted and read only by the runtime. Tools, integrations and carrier accounts reference it as {{secrets.NAME}}; the value is never returned to you, the model or the caller. Every API key, bearer token, signing key or password a tool sends belongs here, never in a prompt, vars or userdata, which the model can see and repeat. There are two sources, read through the one namespace:

	Workspace secret	Session secret
Set by	An admin, `POST /v1/secrets` (Build → Secrets)	`secrets` on the request that starts the session
Read as	`{{secrets.NAME}}` / `input.secrets.NAME`	The same
Name and value rules	See below	The same, at most 20 per session
Lifetime	Until deleted	Until the session’s content is deleted
Same name in both	—	The session’s value wins for that session

Storing a secret

ADMIN only. Dashboard: Build → Secrets. API: POST /v1/secrets, which is an upsert on name.

curl -X POST https://api.talqing.com/v1/secrets \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CRM_API_KEY", "value": "crm_live_8d1f…" }'

const secret = await talqing.secrets.create({
  createSecretRequest: { name: "CRM_API_KEY", value: process.env.CRM_API_KEY! },
});
console.log(secret.name, secret.value_hint); // CRM_API_KEY …9f2c

import os

secret = talqing.secrets.create(name="CRM_API_KEY", value=os.environ["CRM_API_KEY"])
print(secret["name"], secret["value_hint"])

Field	Rule
`name`	Matches `^[A-Za-z_][A-Za-z0-9_]*$`; case-sensitive, unique in the workspace. Dashes, spaces and dots are refused
`value`	1–16,384 characters

Rotating is storing the same name again. The old value is gone immediately (no versions, no undo), and every reference uses the new value from its next run with no republish.

Reading secrets

GET /v1/secrets is readable by every member and returns names only, never values:

{
  "items": [
    {
      "id": "0f4c2b1e-6a3d-4f18-9c77-2b81aa5d0e93",
      "name": "CRM_API_KEY",
      "value_hint": "…9f2c",
      "created_at": "2026-08-11T10:02:41.220Z",
      "updated_at": "2026-08-27T14:36:08.915Z"
    }
  ],
  "has_more": false,
  "limit": 200,
  "offset": 0
}

value_hint is the last four characters. Nothing can reveal a stored value; if you lose the original, store a new one.

Session secrets

A per-session credential — a callback token you mint for one interview, one customer, one call — goes in secrets on the request that starts the session. POST /v1/calls/token, POST /v1/calls/outbound, POST /v1/chats, POST /v1/calls/{session_id}/resume and a tool test run (POST /v1/tools/{tool_id}/run) take it. Batches and task runs do not; their tools see workspace secrets only.

curl -X POST https://api.talqing.com/v1/calls/token \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "3aac08fb-27b5-4454-bf35-bc267bd436f1",
    "secrets": { "TOOL_TOKEN": "tq_cb_6f2a…" }
  }'

const call = await talqing.calls.token({
  tokenRequest: {
    agent_id: "3aac08fb-27b5-4454-bf35-bc267bd436f1",
    secrets: { TOOL_TOKEN: mintCallbackToken(candidate.id) },
  },
});

call = talqing.calls.token(
    agent_id="3aac08fb-27b5-4454-bf35-bc267bd436f1",
    secrets={"TOOL_TOKEN": mint_callback_token(candidate_id)},
)

The agent’s tools read it like any secret:

{ "headers": { "Authorization": "Bearer {{secrets.TOOL_TOKEN}}" } }

The values are never shown to the model, never returned by any endpoint and never put in the browser token; they are stored encrypted with the session.
They reach every agent the session runs: team members, handoff targets and entered tasks.
They are deleted with the session’s content — by your retention policy or DELETE /v1/calls/{session_id} / DELETE /v1/chats/{chat_id}.
A resumed call keeps the dropped call’s secrets; secrets on the resume request adds names or replaces values (a rotated short-lived token).
Inbound calls and chats have no starting request: they see workspace secrets, plus any secrets your inbound webhook answers with.

Where `{{secrets.NAME}}` resolves

A secret can only be sent by an http operation or read by a code operation. Every other operation speaks, shows, stores or compares what it resolves, so a secret there is refused at save.

Place	Resolves?
An `http` operation in a tool’s operation tree: URL, query, headers, body	Yes
A `code` operation	No template syntax; read `input.secrets.NAME`
Integration credential fields; an inline MCP server’s URL and headers (the only root allowed there)	Yes, workspace secrets only
Carrier account credential fields	Yes, workspace secrets only
`say`, `generate_reply`, `add_message`, `set_variable`, `if`, `frontend_rpc`, `handoff`, `transfer`, `send_dtmf`	No. A validation error
An `http` operation’s `method`	No
An agent’s `prompt` or `greeting`	No. A validation error

In an operation the error reads:

tool 'book' / operations[0] / say: reads {{secrets.TOOL_TOKEN}} - a secret can only
be sent by an http operation or read by a code operation, never spoken, shown or stored

In a prompt or greeting the error reads:

the prompt cannot use {{secrets.CRM_API_KEY}} - a workspace secret is a
credential for tools to send, never text for the model

In a code operation, only the secrets the tool names are sent to the sandbox:

export default async function handler(input) {
  const res = await fetch("https://api.example.com/orders", {
    headers: { Authorization: `Bearer ${input.secrets.CRM_API_KEY}` },
  });
  return await res.json();
}

A string that is exactly one token resolves to the stored value as-is; a token inside a longer string is substituted as text:

{
  "headers": { "Authorization": "Bearer {{secrets.CRM_API_KEY}}" },
  "body": { "token": "{{secrets.CRM_API_KEY}}" }
}

A missing secret fails loudly

A reference never resolves to an empty string.

At save and publish: a tool reading a name the workspace does not have is a warning — every session must supply it in secrets, and an inbound call or chat will fail the tool. An inline MCP server, integration or carrier account referencing a missing name is an error.
At session start: a request whose agents’ tools read a name that is neither a workspace secret nor in its secrets is refused with 400, this session needs secrets it was not given, one line per name: tool 'book' reads {{secrets.TOOL_TOKEN}}, which is not a workspace secret and was not supplied. Handoff targets outside the session’s team are not checked here.
At runtime: if a tool meets a missing secret anyway, it fails before any operation runs with secret 'NAME' is not a workspace secret and was not supplied for this session, the model gets the standard tool-failure message, and tool.failed fires.

A value an endpoint echoes back in its response reaches the model like any other response field. Do not call endpoints that reflect credentials.

Deleting a secret

DELETE /v1/secrets/{secret_id}, ADMIN only. A secret still referenced is refused with 409, naming each user:

secret 'CRM_API_KEY' is used by tool 'lookup_order', integration 'CRM' — remove it there before deleting it

References that block deletion: a tool’s draft or published version; an older tool version still pinned by a published agent or task (republish that agent too, see the pin rule); an integration or carrier account. Tool versions nothing runs do not block.

Plaintext in integrations and carrier accounts

Integration and carrier-account credential fields accept either a reference ({{secrets.RESEND_API_KEY}}, which must exist) or raw plaintext. Plaintext is stored as a new secret under a default name such as RESEND_API_KEY, or a suffixed name like RESEND_API_KEY_a91c if that name is taken, and only the reference is kept on the integration. Existing secrets are never overwritten this way.

Templating and data

The six roots a tool operation can read.

Provider keys

The separate store for the model keys your agents run on.

Get started

Build

Guides

Storing a secret

Reading secrets

Session secrets

Where `{{secrets.NAME}}` resolves

A missing secret fails loudly

Deleting a secret

Plaintext in integrations and carrier accounts

Next

Templating and data

Provider keys

​Storing a secret

​Reading secrets

​Session secrets

​Where {{secrets.NAME}} resolves

​A missing secret fails loudly

​Deleting a secret

​Plaintext in integrations and carrier accounts

​Next

Templating and data

Provider keys

Storing a secret

Reading secrets

Session secrets

Where `{{secrets.NAME}}` resolves

A missing secret fails loudly

Deleting a secret

Plaintext in integrations and carrier accounts

Next