> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callkaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets for Agents

> Store credentials securely and reference them from agents without placing secret values in agent configuration

Secrets are credentials such as API keys, access tokens, and passwords that an agent or workflow needs to connect to another service. Store these values in the organization secrets registry instead of placing them directly in prompts, functions, webhook headers, or AI FDE chats.

Open [**Dashboard → Settings → Secrets**](https://callkaro.ai/dashboard/settings/secrets) to manage the registry.

## How secret references work

Each secret has a **name** and a **value**. Agent configuration stores only a reference in this format:

```text theme={null}
x_secrets.SECRET_NAME
```

For example, an agent can refer to `x_secrets.CRM_API_KEY`. The saved agent version contains the reference, not the credential value. CallKaro resolves supported secret fields from your organization's registry when they are used.

<Info>
  Secret names are case-sensitive. Use a stable name made from letters, numbers, underscores, or hyphens, without spaces. Examples: `CRM_API_KEY`, `booking-token`, and `SALESFORCE_PASSWORD`.
</Info>

## Add a secret

<Steps>
  <Step title="Open Secrets settings">
    Go to [**Dashboard → Settings → Secrets**](https://callkaro.ai/dashboard/settings/secrets).
  </Step>

  <Step title="Add the name and value">
    Select **Add Secrets**, enter a descriptive name, and paste the real credential into **Value**.
  </Step>

  <Step title="Save the registry">
    Select **Save**. The value is masked after saving; the secret name remains available for selection in supported Agent Builder fields.
  </Step>
</Steps>

If you cannot view or change Secrets settings, ask your organization admin for the required Secrets permission or ask them to add the secret for you. Share the required **name and purpose** through your approved internal process. Do not paste the value into an agent prompt or AI FDE chat.

## Use a secret in an agent

Where the Agent Builder offers a **Secrets** source, select it and choose the saved secret name. For fields that accept a reference directly, enter the exact `x_secrets.NAME` value.

Common uses include:

* Authentication values in pre-call, in-call, and post-call functions.
* API keys and tokens used by custom functions.
* Agent webhook header values.
* Other credential-bearing settings that show a Secrets selector.

```text theme={null}
x_secrets.CRM_API_KEY
```

Do not add quotes, spaces, or a different spelling to the secret name. If a destination requires a complete header value such as `Bearer <token>`, store the complete value expected by that field in the registry when the field resolves only an exact secret reference.

## Use secrets with AI FDE

AI FDE can see available secret **names**, but it does not receive their values. When it creates or changes a credential-bearing field, it uses an existing matching name when possible.

If no matching name exists, AI FDE can save a descriptive reference such as `x_secrets.CRM_API_KEY` as a **pending secret**. Saving the agent version is not blocked. After the save, AI FDE reports each pending name and directs you to [Secrets settings](https://callkaro.ai/dashboard/settings/secrets).

Add every reported name exactly as shown before using the affected integration. If you do not manage the registry, ask your admin to add those names. Once a matching secret is available, the saved reference can resolve without placing the credential value in the agent version.

<Warning>
  A saved version with pending secrets is not fully configured for the operations that need them. Test the affected function or webhook after adding the secrets and before publishing or using the version for live calls.
</Warning>

## Update, rotate, rename, or delete

* **Update or rotate a value:** Select the edit icon beside the secret, enter the replacement value, and save. Agents that use the same name continue to reference it.
* **Rename a secret:** Update every agent and version that uses the old name. References are matched by exact name and are not renamed automatically.
* **Delete a secret:** Remove it only after confirming that no active agent, version, function, or webhook still references it.
* **Keep a value unchanged:** Do not open its value editor. Existing values remain masked and are retained when other registry entries are saved.

Use one clear name per credential purpose, rotate credentials regularly, and grant each credential only the permissions its integration needs.

## Troubleshooting

| Issue                                             | What to check                                                                                   |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| AI FDE reports a pending secret                   | Add the exact reported name in Secrets settings, including capitalization.                      |
| A function or webhook cannot authenticate         | Confirm the referenced name exists and its stored value is current and has the required access. |
| The Secrets selector is empty                     | Add a secret first, or ask an admin with Secrets permission to add it.                          |
| An integration stopped after a rename or deletion | Restore the old name or update every affected agent version to use the new name.                |