Securely store and use API keys and secrets in Paige

Secrets are how you store sensitive values — API keys, credentials, tokens — that your bot needs at runtime. Each secret is encrypted at rest and scoped to a single project. When your bot code runs, Paige decrypts the secrets for that project and injects them as environment variables. Your code reads them with process.env.SECRET_NAME, just like any other environment variable.

How secrets work

Secrets are stored as encrypted key-value pairs. The key becomes the environment variable name in your bot code. The value is the sensitive string you want to protect — an API key, a bearer token, a database password. Secrets are:

Encrypted at rest — stored in an encrypted form and decrypted only when needed
Per-project — a secret in one project is never accessible from another. Two projects in the same workspace don’t share secrets
Not tied to Deploy — unlike your bot code, secrets don’t have a preview and a live copy. There’s one value, used everywhere

For Airtable and Slack, don’t store a raw token here — use Connectors instead. Connectors handle the sign-in for you and keep the credential out of your hands entirely. Secrets are the right tool for everything else.

Adding a secret

Open the Tools tab and select Secrets, then click Add Secret. Enter a key name and the secret value, then click Save. Key naming rules:

Start with a letter, then uppercase letters, numbers, and underscores (e.g. OPENAI_API_KEY, CRM_API_TOKEN)
The field uppercases as you type, so typing openai_api_key gives you OPENAI_API_KEY
No spaces or special characters other than underscores

Secrets are readable by anyone who can open your project. Values are hidden behind dots in the list, but the eye icon reveals the real value and the copy icon copies it. Treat project access as equivalent to access to every credential in it — that matters when you invite someone to a workspace.

Adding a secret with a key that already exists overwrites the old value without warning — there’s no “this key already exists” prompt. If you meant to add a second credential, give it a different key.

Accessing secrets in bot code

Once a secret is saved, access it in your bot code using process.env:

// Access a stored secret by its key name
const openAiKey = process.env.OPENAI_API_KEY;
const crmToken = process.env.CRM_API_TOKEN;
const webhookSecret = process.env.WEBHOOK_SECRET;

You can reference secrets anywhere in your bot code — in service files, route handlers, or utility functions.

// Example: initialise the OpenAI client using a stored secret
const OpenAI = require("openai");

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Example: authenticate a third-party API call
const response = await fetch("https://api.example-crm.com/contacts", {
  headers: {
    Authorization: `Bearer ${process.env.CRM_API_TOKEN}`,
  },
});

Managing secrets

List secrets
Update a secret
Delete a secret

Tools → Secrets lists every key in your project with the date it was last updated. Values are masked by default; click the eye icon on a row to reveal one, or the copy icon to copy it to your clipboard.

Click Delete on the row and confirm. Once deleted, any bot code that references process.env.KEY_NAME will receive undefined until you add the key back.

Deleting a secret that your bot code depends on will cause runtime errors. Make sure to update or remove the references in your bot code before deleting a secret.

Common use cases

OpenAI API key

If your bot uses the AI template, it requires an OpenAI API key for generating responses and transcribing voice notes.Add a secret with key OPENAI_API_KEY and your OpenAI key as the value. The template reads it automatically via process.env.OPENAI_API_KEY.

CRM API credentials

If your bot looks up or creates contacts in a CRM (HubSpot, Zoho, Salesforce, etc.), store the API key or OAuth token as a secret.For example, add HUBSPOT_API_KEY and reference it in your integration service:

const hubspot = require("@hubspot/api-client");
const client = new hubspot.Client({ accessToken: process.env.HUBSPOT_API_KEY });

Third-party service credentials

Any external service your bot calls — payment processors, SMS gateways, scheduling APIs, email services — should have their credentials stored as secrets rather than hardcoded in your bot code.Common examples:

STRIPE_SECRET_KEY for payment processing
SENDGRID_API_KEY for email sending
GOOGLE_MAPS_API_KEY for location lookups

Webhook verification tokens

If your bot calls an external service that sends webhooks back to you, store the shared secret or verification token used to validate incoming requests.

const incomingSignature = req.headers["x-webhook-signature"];
const expectedSignature = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest("hex");

if (incomingSignature !== expectedSignature) {
  return res.sendStatus(401);
}

Security notes

Do not hardcode sensitive values in your bot code files. Secrets in process.env at least stay out of your version history; a key pasted into code is in every snapshot from then on.
A rotated secret isn’t live immediately. Your bot keeps a warm copy of its environment for a few minutes after it last ran, so a busy bot can carry on using the old value for a little while. If the rotation matters — a leaked key, say — deploy straight afterwards to force the new value through.
Secrets are not available in flow JSON files. Flows run on Meta’s infrastructure, not Paige’s runtime. If a flow needs a dynamic value, pass it as a flow action payload from your bot code instead.
Scheduled tasks get a narrower environment than your webhook code. Your secrets are there, but Connector credentials aren’t — see Scheduled Tasks.

AI agents

Flows

Broadcasts

Conversations

Preview

Tools

Settings

Securely store and use API keys and secrets in Paige

How secrets work

Adding a secret

Accessing secrets in bot code

Managing secrets

Common use cases

Security notes

​How secrets work

​Adding a secret

​Accessing secrets in bot code

​Managing secrets

​Common use cases

​Security notes

How secrets work

Adding a secret

Accessing secrets in bot code

Managing secrets

Common use cases

Security notes