Skip to main content

API secrets management

API secrets allow you to securely store sensitive credentials like API keys, authentication tokens, and passwords that your agent needs to access external systems. Instead of hardcoding these values in your agent configuration, you store them securely and reference them by name.

Why use secrets​

Security benefits:

  • Credentials never appear in plain text in your configuration
  • Secrets are encrypted at rest
  • Access is logged and auditable
  • Easy to rotate without changing agent configuration
  • Team members can use secrets without seeing actual values

Common uses:

  • API keys for external services
  • Authentication tokens
  • Database passwords
  • OAuth client secrets
  • Third-party service credentials

Managing secrets​

Accessing Secrets​

  1. Navigate to Secrets from the main menu in Studio
  2. View all secrets for your organization
  3. Add, edit, or delete secrets as needed

Creating a Secret​

  1. Click Add secret
  2. Enter a Secret name: Use a descriptive, clear name (e.g., stripe_api_key, sendgrid_token)
  3. Enter the secret value for each environment (Development, Staging, Production). Each environment can have a different value, allowing you to use separate credentials for testing and production.
  4. Click Save

Naming best practices:

  • Use lowercase with underscores (e.g., my_api_key)
  • Be descriptive (e.g., hubspot_api_token not token1)
  • Include the service name (e.g., twilio_account_sid)
  • Avoid spaces or special characters

Editing a Secret​

  1. Find the secret in the list
  2. Click Edit
  3. Update the secret value
  4. Click Save

Note: The secret name cannot be changed once created. Create a new secret if you need a different name.

Deleting a Secret​

  1. Find the secret in the list
  2. Click Delete
  3. Confirm deletion
Before Deleting

Ensure no agents are using this secret. Deleting an active secret will cause actions using it to fail.

Environments​

Secrets support per-environment values so you can use different credentials for each stage of your workflow:

  • Development: Use sandbox or test API keys for building and debugging.
  • Staging: Use pre-production credentials for validation before going live.
  • Production: Use live credentials for real customer conversations.

When an action executes, the correct secret value is automatically resolved based on the environment of the conversation. For example, a playground session set to "Development" uses the development secret values, while a phone call through a production connector uses the production values.

tip

If you only need a single value across all environments, you can set the same value for each. However, using separate credentials per environment is recommended for safe testing and credential isolation.

Using secrets​

Secrets are used through other features rather than referenced directly in actions:

  • Auth connectors: Select a secret for the token, API key, client secret, or password. See auth connectors.
  • API connection headers: Add a header with type "Secret" and select the secret. See API connections.
  • Action headers: When configuring headers directly on an action, select type "Secret" to reference a secret value.

In all cases, the correct per-environment value is used automatically based on the conversation's environment.

Security Best Practices​

Rotate Secrets Regularly​

  • Change API keys periodically
  • Especially after team member departures
  • Follow your security policies
  • Update in Stellar secrets management

Use Minimal Permissions​

  • API keys should have only necessary permissions
  • Don't use admin keys when read-only works
  • Follow principle of least privilege
  • Review and audit permissions

Don't Share Secrets​

  • Never share secret values via email or chat
  • Don't include in documentation
  • Don't commit to version control
  • Use secrets management for sharing

Monitor Secret Usage​

  • Review which secrets are in use
  • Remove unused secrets
  • Audit access logs
  • Track changes to secrets

Limit Access​

  • Only authorized team members should manage secrets
  • Use role-based access control
  • Review team access regularly
  • Remove access when no longer needed

Troubleshooting​

Action failing due to secret​

Check:

  • Secret name is spelled correctly (case-sensitive)
  • Secret exists on the Secrets page
  • Secret value is correct and valid
  • API key hasn't expired or been revoked
  • The correct environment has a value configured

Authentication Failures​

  • Confirm secret value is current and valid
  • Check if API key was revoked or expired
  • Test the credential directly with the API
  • Verify correct credential type (token vs. key vs. password)

Organization-Level Secrets​

Secrets are shared across your organization:

  • All agents in your org can use any secret
  • Team members with access can view and edit
  • Useful for commonly-used credentials
  • Ensures consistency across agents
  • Each secret maintains separate per-environment values across the organization
Self-Service Team Management

Advanced team and access management features (like role-based secret access) are planned for future releases. Currently, all organization members can access all secrets.

Next Steps​

After setting up secrets:

  • Create actions that use these secrets
  • Test actions to ensure secrets work correctly
  • Document which secrets each agent uses
  • Establish a secret rotation schedule
  • Review and audit secret usage regularly