Variables and secrets

Variables and secrets are two kinds of stored values your agents use. A variable is a plain value, like your support phone number or return window, that you write once and drop into prompt blocks as {{name}}. A secret is an API key or token that your tools and Functions send to your own systems. It is stored encrypted, and neither you nor the AI can read it back after you save it.

	Variables	Secrets
What it holds	Text the agent may read and repeat	API keys and tokens
Where you use it	Prompt blocks, as {{name}}	Tools (the API key setting) and Functions (Keys)
Who it belongs to	The whole workspace, shared by every agent	One agent
Can you read it again?	Yes	No, only the last four characters
Does the AI see it?	Yes, filled into the instructions	Never
Versioned with the agent?	No, a change applies at once	No, a change applies at once
Where you manage it	Settings → Variables	Settings → Secrets, or while setting up a tool or Function

Variables

When to use a variable

Use a variable for a fact that appears in several blocks or several agents and that you may change later. Typical examples:

• {{support_phone}}: a support line you print in a handoff block and a closing block.
• {{return_days}}: the return window of an online store.
• {{clinic_address}}: a dental clinic's address, used by its booking agent and its FAQ agent.

When the value changes, you edit it once in Settings → Variables. Every agent uses the new value from its next reply. You don't need to publish.

tip

A variable is a good fit for anything you'd otherwise have to find and replace by hand. If a value is long, structured or only matters for one topic, put it in Knowledge instead.

Built-in variables

Three variables are filled by Peki on every turn. You can't create, rename or change them.

Variable	What it holds
{{customer.name}}	The customer's name, from their customer profile in the Inbox, or the Customer name you set in the Test panel. Empty when the name isn't known.
{{business.name}}	Your workspace name.
{{today}}	Today's date in your workspace timezone, written in English, for example Monday 26 October 2026.

note

With Protect personal data and Also hide the customer's name from the AI turned on (both are on by default), {{customer.name}} reaches the AI as a placeholder like [NAME_1]. Customers still see their real name in replies. See Guardrails and privacy.

Create a variable

You need the Editor role or higher. Viewers see the list but can't change it.

1. Go to Settings → Variables.
2. In the add row at the bottom of Your variables, fill in:
   • Name: what you'll type between the braces, for example support_phone.
   • Value: what the agent reads in its place.
   • Description (optional): a note for your team.
3. Click Add variable.

Field	Rules
Name	Lowercase letters, digits and _. Must start with a letter. Up to 40 characters. Unique in the workspace. The field turns capitals and other characters into lowercase and _ as you type.
Value	Up to 1,000 characters. Can be empty.
Description (optional)	Up to 200 characters. Only your team sees it.

You can't use the name of a built-in variable, and names with dots are reserved for built-ins.

To change a variable, edit its value or description in its row and click Save. To remove it, click Delete and confirm.

warning

Deleting a variable doesn't touch the blocks that use it. Wherever {{name}} appears, the agent gets an empty value from the next reply on. Search your prompt blocks before you delete one.

Use a variable in a prompt block

Type {{name}} anywhere in a block's text, or use the variable picker:

1. Open Instructions and click into the block where the value belongs.
2. Click { } (Insert variable) at the top right of the block.
3. Pick a built-in or one of your variables. It's inserted at the cursor.

The picker also has a Manage variables link to Settings → Variables.

Spaces inside the braces are allowed, so {{ support_phone }} works too. An example block for an online store:

If the customer wants to return an item, explain that returns are accepted
within {{return_days}} days of delivery. For anything else, they can call
{{support_phone}}.

If a block uses a name that isn't built in and doesn't exist in the workspace, the block shows a warning: Unknown variable {{name}} — it will be empty. Create it in Settings → Variables. The draft still saves, and the variable renders as empty text until you create it.

Where variables work

Variables are filled in prompt blocks only. Text elsewhere is sent as written, so {{support_phone}} stays literal in:

• skill instructions,
• tool and Function descriptions, URLs and headers,
• knowledge sources,
• the fallback reply and guardrail replies.

To check the result, click Preview final prompt on the Instructions page. The preview shows every block with its variables already filled. See Testing.

Variables and versions

Variables aren't part of an agent version. Changing a value in Settings affects the published agent at once, without a publish, and restoring an old version doesn't bring back old variable values. If you want a change to go out only with a publish, write the value into the block itself.

Secrets

What a secret is

A secret is an API key, bearer token or similar credential that a tool or Function needs to call your systems: your store's order API, your booking system, your CRM. Peki keeps it encrypted and adds it to the request on its own side, right before the request leaves. The AI never sees the value. It only knows the tool exists.

Each secret has:

Part	What it means
Agent	The one agent whose tools and Functions may use it. Another agent's tools can't use it, even in the same workspace.
Name	A label you choose, for example ShopX API. Up to 80 characters, unique within the agent. Functions refer to secrets by this name.
Value	The key itself. 4 to 4,000 characters (Functions need at least 8). After saving, only its last four characters show, as ····a1b2.
Allowed sites	The only hosts the key is ever sent to, such as api.yourshop.com, or *.yourshop.com for every subdomain. Up to 10.

There are two kinds of secret:

• Key (the usual kind): sent to its allowed sites by tools and Functions.
• Signing secret: a webhook signing secret, used only to check the signatures of incoming requests on a webhook trigger. Peki never sends it anywhere, so it has no allowed sites. See Triggers.

Add a secret while setting up a tool

This is the quickest way, because the allowed site is filled in for you.

1. On the Tools page, open the tool and choose how the key is sent under API key: Bearer token or Key in a header (then enter the Header name). No key means the tool sends no key.
2. Open Choose a key and pick + Add a new key.
3. Fill in:
   • Key name, e.g. ShopX API
   • Paste the key: the field is masked as you type.
   • Allowed sites: if you leave it empty, Peki uses the host of the tool's URL.
4. Click Save key. The new key is selected for the tool.

For Functions, the same picker sits under Keys. Choose Where the key goes:

• Header: by default Authorization: Bearer <key>. Enter a Header name to use another header instead.
• Query: the key is added as the Query parameter you name.

The Function's code never holds the value. It asks for the key by name, and the network proxy adds it to requests going to sites that both the Function and the key allow. See Functions.

Add a secret in Settings

1. Go to Settings → Secrets.
2. In the form under the list, choose the Agent, enter the key name, paste the key and enter at least one allowed site (comma-separated for several).
3. Click Save key.

You need an agent first, because every key belongs to one. Settings → Secrets groups keys by agent.

tip

You can also give the Copilot a key through its API key card. If you paste a key straight into the Copilot chat, Peki removes it before the model sees the message.

How secrets are shown

After you save a key, nobody can read its value again. Not you, not an admin, not the AI. Peki only ever shows:

• its name,
• its last four characters (····a1b2),
• its allowed sites (Sent only to api.yourshop.com).

When an API echoes a key back, for example in an error message, Peki replaces it in the response before the AI or the tool's Try it panel sees it. A long key shows as ···· plus its last four characters. A key of 8 characters or fewer shows only as ····.

Allowed sites

A key only goes to the sites it was saved for. If someone changes a tool's URL to another host, the key isn't sent and the call fails with a clear error. That's what stops anyone who can edit a tool from sending your key to a server they control.

• Use plain host names: api.yourshop.com, not https://api.yourshop.com/v1.
• *.yourshop.com matches every subdomain, like api.yourshop.com and eu.api.yourshop.com, but not yourshop.com itself.
• If a tool's host isn't among its key's sites, the tool shows: This key may only be sent to … not ….

Only admins can change a key's sites, with Change sites in Settings → Secrets. Pointing a key at a new site is exactly how it could be read, so editors can't do it.

Who can do what

Action	Role needed
See the list of keys (names, last four, sites)	Editor
Add a key	Editor
Pick a key for a tool or Function	Editor
Change a key's allowed sites	Admin
Assign an unassigned key to an agent	Admin
Remove a key	Admin

See Members and roles.

Unassigned keys

Keys saved before keys belonged to agents appear under Unassigned in Settings → Secrets. No tool can use them until an admin picks an agent with Assign to…. Once a key belongs to an agent it can't be moved to another one, because that would silently break the first agent's tools. Add a new key for the other agent instead.

Rotate a key

You can't edit a saved key's value. To replace it, add a new key and switch over. HTTP tools point at a key by its identity, while Functions point at it by name, so the steps differ.

For HTTP tools:

1. Add the new key to the same agent under a new name, for example ShopX API 2026.
2. In each tool that used the old key, pick the new one under API key.
3. Publish. Tool settings are part of the agent version, so the live agent keeps using the old key until you publish.
4. In Settings → Secrets, remove the old key.

For Functions:

1. Remove the old key in Settings → Secrets.
2. Add the new key to the same agent with exactly the same name.

The Function picks up the new key on its next call, with no publish. Calls made between the two steps fail, so do this when traffic is low. If you'd rather avoid any gap, give the new key a new name, select it under Keys in the Function, publish, then remove the old key.

warning

Removing a key breaks every tool that uses it. Its calls fail with The API key for this tool was deleted until you choose another key. Revoke the old key in your own system only after the switch is live.

Errors you may see

Error in the tool result or trace	What it means	What to do
The API key for this tool was deleted	The selected key was removed.	Pick another key for the tool and publish.
This API key belongs to another agent	The tool was copied from another agent with its key.	Add a key for this agent.
This API key is not assigned to an agent yet	It's an unassigned key.	Ask an admin to assign it.
This API key may only be sent to …	The tool's URL host isn't among the key's allowed sites.	Fix the URL, or ask an admin to add the site.
This API key has no allowed sites yet	The key has no sites.	Ask an admin to add one with Change sites.
This key is a webhook signing key	A signing secret was chosen for an outgoing call.	Pick a regular key.

Related

• Instructions
• Tools
• Functions
• Guardrails and privacy
• Triggers
• Members and roles
• Security model