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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/secrets/how-to-setup",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# How to create a secret

> Create a secret in the Secrets Vault

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

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

## Create a secret

<Steps>
  <Step title="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.
    </Note>
  </Step>

  <Step title="Add a new secret">
    Click **Add secret** in the top right corner.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save">
    Click **Add** to create the secret.
  </Step>
</Steps>

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

## 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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](/secrets/how-to-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.

## Related pages

<CardGroup cols={2}>
  <Card title="Manage access control" icon="shield-halved" href="/secrets/how-to-access-control">
    Grant secrets to specific agents and control permissions.
  </Card>

  <Card title="Secrets overview" icon="lock" href="/secrets/introduction">
    Understand secrets and why they matter.
  </Card>
</CardGroup>