> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# How to create a secret

> Create a secret in the Secrets Vault

> **Info**
>
> **This page requires Python familiarity.** Secrets are accessed from Python [functions](/agent-studio/tools/overview) using `conv.utils.get_secret()`.

Create secrets to store API keys, tokens, or other credentials that your agent's [functions](/agent-studio/tools/overview) need at runtime.

## Create a secret

#### Open the Secrets Vault

From the workspace homepage, click the **Secrets** tab in the top bar (next to **Agents**, **Users**, and **API Keys**).

> **Note**
>
> The Secrets tab is only visible to **workspace admins** on supported workspaces. If you're an admin and can't see it, the Secrets Vault may not be enabled for your account yet — contact PolyAI support to request access.

#### Add a new secret

Click **Add secret** in the top right corner.

#### Fill in the details

* **Name** – Use a descriptive, lowercase name with underscores (e.g., `stripe_api_key`, `booking_service_token`). This is the identifier you pass to `conv.utils.get_secret()` in your functions.
* **Description** (optional) – Explain what the secret is for and which integration it supports.
* **Value** – Store as a single value (a plain string like an API key) or key/value pairs (a dictionary for grouped credentials like `client_id` and `client_secret`).

#### Grant agent access

Under **Agent access**, select which agents can retrieve this secret. Only selected agents can use `conv.utils.get_secret()` to access this value.

#### Save

Click **Add** to create the secret.

> **Note**
>
> Agents without access granted here cannot retrieve the secret. You can update access later from the [access control](/advanced/secrets/access-control) page.

## Using secrets in functions

The `conv.utils.get_secret` method lets you securely retrieve the contents of secrets added to your account. Use it inside any function that has access to the `conv` object:

```python
secret_value = conv.utils.get_secret('name of your secret')
```

### Return values

**For a key-value type secret**, the function returns a dictionary of key-value pairs:

```python
{
    "secret_key": "secret_value"
}
```

You can access this like a standard Python dictionary in your function code.

**For a single type secret**, the function returns the string containing the secret value.

### Tips

* **Check available secrets**: There is a box called "Secrets" on the top right corner of the "Function Definition" box in the Function Editor. Click that to see what secrets your agent has access to.
* **Permission issues**: If you cannot see the secret in the "Secrets" box, refer to the [access control for secrets](/advanced/secrets/access-control) page to add permission for your function.
* **Copy code snippet**: In the "Secrets" box, you can also copy the code snippet for accessing the secret directly into your function code.

## Next steps

#### [Manage access control](/advanced/secrets/access-control)

Grant secrets to specific agents and control permissions

#### [Use secrets in functions](/agent-studio/tools/create-tool)

Write Python functions that call external APIs using your stored credentials