Secrets

Secrets require Solo plan or higher. See Plans for details.

Secrets are encrypted storage for API keys, tokens, and other credentials your app needs to connect to external services. They keep sensitive values out of your app configuration, builder UI, and trace logs.

When to Use Secrets

Create a secret any time your app needs a value that should not be visible to collaborators or logged in traces:

API keys (Stripe, Twilio, OpenAI, etc.)
Bearer tokens and access tokens
Database connection strings
Webhook signing secrets

Create a Secret

Open Secrets settings

In the builder, go to your app’s Secrets settings.

Secrets settings panel in the builder — The Secrets settings panel

Add a new secret

Click Add Secret. Enter a name and the secret value.

Add secret dialog with name and value fields — Adding a new secret

Name it clearly. Use the SERVICE_PURPOSE format so anyone on your team can identify what the secret is for at a glance:

Good Name	What It Stores
`STRIPE_SECRET_KEY`	Stripe API secret key
`CRM_API_TOKEN`	CRM service access token
`SENDGRID_API_KEY`	SendGrid email API key
`INTERNAL_DB_PASSWORD`	Internal database password

Avoid vague names like API_KEY, TOKEN, or SECRET. These become confusing as your app grows.

Save the secret

Click Save. The value is encrypted and stored. You will not be able to view the value again after saving; you can only update or delete it.

Secret saved confirmation — Secret saved successfully

Use Secrets in Endpoints

Reference a secret in any endpoint header, path, or request body using the {{secrets.YOUR_SECRET_NAME}} syntax. Example: Authorization header

Authorization: Bearer {{secrets.STRIPE_SECRET_KEY}}

Example: API key as a query parameter

/api/data?api_key={{secrets.CRM_API_TOKEN}}

The secret value is injected at request time. It never appears in the builder UI, app configuration exports, or trace logs.

If you reference a secret name that does not exist, the request will fail with an empty value. Double-check the exact name in your Secrets settings.

Rotate a Secret

When a credential expires or you need to cycle keys:

Update the secret value

Open Secrets settings, find the secret, and click Update. Enter the new value and save.

Retest affected tools

Open the preview panel and invoke each tool that uses the rotated secret. Confirm that requests succeed with the new credential.

Check traces

Review Traces for the tools you tested. Verify that requests completed successfully and no errors appeared after the rotation.

Naming Conventions

Consistent naming prevents confusion, especially on teams. Follow the SERVICE_PURPOSE pattern:

STRIPE_SECRET_KEY        -- not "stripe" or "sk_live"
TWILIO_AUTH_TOKEN         -- not "twilio_token"
POSTGRES_CONNECTION_URL   -- not "db_url"
GITHUB_PERSONAL_TOKEN     -- not "gh_pat"

When you have multiple keys for the same service (e.g., test and production), include the environment:

STRIPE_SECRET_KEY_TEST
STRIPE_SECRET_KEY_PROD

Troubleshooting

Problem	Likely Cause	Fix
Integration fails after key rotation	The new value was not saved, or the wrong secret was updated	Open Secrets settings and confirm the correct secret was updated. Retest the affected tool in preview.
Team members confused about which secret to use	Vague or inconsistent naming	Rename secrets using the `SERVICE_PURPOSE` format. Delete unused secrets.
`{{secrets.X}}` appears literally in the request	The secret name is misspelled or does not exist	Check the exact name in Secrets settings. Names are case-sensitive.
Secret value seems stale after update	Browser cache or old preview session	Refresh the preview panel and invoke the tool again.

Getting Started

Building Apps

Connecting Services

Connecting to ChatGPT

Testing & Quality

Analytics

Team & Billing

Advanced

Secrets

Secrets

When to Use Secrets

Create a Secret

Use Secrets in Endpoints

Rotate a Secret

Naming Conventions

Troubleshooting

What’s Next

API Integrations

Traces

​Secrets

​When to Use Secrets

​Create a Secret

​Use Secrets in Endpoints

​Rotate a Secret

​Naming Conventions

​Troubleshooting

​What’s Next

API Integrations

Traces

Secrets

When to Use Secrets

Create a Secret

Use Secrets in Endpoints

Rotate a Secret

Naming Conventions

Troubleshooting

What’s Next