Skip to main content
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 Data access).
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 allows you to 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.
Last modified on March 27, 2026