How to create a secret

Create a secret in the Secrets Vault

This page requires Python familiarity. Secrets are accessed from Python functions using conv.utils.get_secret().

Create secrets to store API keys, tokens, or other credentials that your agent’s functions need at runtime.

Create a secret

1. Open the Secrets Vault

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

2. Add a new secret

   Click Add secret in the top right corner.

3. 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).
4. 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.

5. Save

   Click Add to create the secret.

Agents without access granted here cannot retrieve the secret. You can update access later from the 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:

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:

{
    "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 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

Manage access control

Grant secrets to specific agents and control permissions.

Secrets overview

Understand secrets and why they matter.