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

After creating a secret, retrieve it in any function:

api_key = conv.utils.get_secret("stripe_api_key")

See using secrets in functions for more examples.