Skip to main content

Documentation Index

Fetch the complete documentation index at: https://howto.paigeme.dev/llms.txt

Use this file to discover all available pages before exploring further.

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; the plaintext value is only available at runtime when your bot executes
  • Per-project — a secret in one project is never accessible from another
  • Not logged — Paige does not include secret values in execution logs or error messages

​
Adding a secret

Navigate to your project’s Settings and open the Secrets section. Enter a key name and the secret value, then save. Key naming rules:
  • Use uppercase letters, numbers, and underscores (e.g. OPENAI_API_KEY, CRM_API_TOKEN)
  • Keys are case-sensitive
  • No spaces or special characters other than underscores
After saving, the secret value is masked in the dashboard. You can overwrite a secret by saving a new value for the same key, or delete it entirely. You cannot read back the stored value once it has been saved.

​
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

To see all secret keys stored for your project (not their values), navigate to Settings → Secrets in your project dashboard. The list shows key names and the date each secret was last updated.
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

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.
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 });
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
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. Anyone with access to your project can read the code; secrets in process.env are not exposed in the code editor.
  • Rotate secrets regularly for high-sensitivity credentials. Update the value in Settings → Secrets and your bot picks up the new value on the next execution.
  • 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.