Storing API keys with agent secrets Guide

When an agent needs to call an outside service — a payment tool, a webhook, a weather or data API — it usually needs an API key or token to authenticate. Secrets are a secure vault where you store those values so your agent can use them without ever exposing them.

How agent secrets work

Each secret is a named value you save to an agent. Values are encrypted when you save them and are injected only at run time, at the exact moment the agent calls the external service. The agent references a secret by its name using the placeholder {{secret:NAME}} — the actual value never becomes part of the agent's reasoning and is never shown back to you or written into its output.

This means you can give an agent the credentials it needs while keeping those credentials private and protected.

Tip: Think of a secret's name as a label the agent uses to find the right key, and the value as the key itself. The agent only ever sees the label — Praxivara supplies the real value securely behind the scenes.

Add a secret

1. Open the agent you want to configure and go to its detail page.
2. In the left-hand Configure navigation, open the Secrets tab.
3. Add a new secret and give it a name, the value (the API key or token itself), and an optional description to remind you what it's for.
4. Save. Once saved, the value is hidden — you'll see that the secret is set, but not the value itself.

The Secrets tab shows all of an agent's secrets at a glance, including which ones are set and which are still empty, so you can quickly spot anything the agent is waiting on.

Choosing the right name

The name matters: your agent references a secret by its exact name with {{secret:NAME}}. If you're setting up the secret yourself, match the name the agent expects. If the AI builder (Stan) is helping you build the agent, it will tell you which name it's looking for — the easiest approach is to use the name it requests.

Where to get the value

The API key or token comes from the outside service itself — for example, a key generated in that service's own dashboard or developer settings. Copy it from there and paste it into the value field. Praxivara stores it securely from that point on.

Adding secrets through the AI builder

Often you won't need to visit the Secrets tab at all. As you describe what you want an agent to do on the Build tab, the AI builder wires up the capabilities it needs. When a task requires an external credential, the builder can request it from you directly with a prompt to paste in the value.

Either path works and lands in the same place — you can always add or review secrets yourself on the Secrets tab, whether or not the builder asked for them.

Edit or remove a secret

• Update a value — Open the Secrets tab and edit the secret to paste in a new value, for example after rotating a key in the outside service.
• Update the description — Edit the description at any time to keep notes clear for your team.
• Delete a secret — Remove a secret the agent no longer needs. Do this if you retire an integration or want to revoke access.

When an agent can't reach a service

If an agent fails to call an external service, an empty or missing secret is a common cause. Check the Secrets tab and confirm that:

• The secret the agent expects actually exists and shows as set, not empty.
• The name matches exactly what the agent references with {{secret:NAME}}.
• The value is current — if you rotated or revoked the key in the outside service, paste the new one in.

If everything looks right and the agent still can't connect, the issue may be with the credential itself in the outside service rather than with the secret in Praxivara.

Note: Secrets hold credentials for calling outside services. If you want to give your agent reference material to read on every run — product docs, price lists, brand guidelines — use its Knowledge instead.