Concepts

Environments & Keys

Production, staging, and how to work with both safely

Two environments, one codebase

Pyramid AI runs two completely separate environments:

ProductionStaging (Sandbox)
Domainapi.pyramid-ai.comapi-staging.pyramid-ai.com
Key prefixpai_live_pai_test_
DatabaseProduction dataIsolated test data
PurposeReal client integrationsDevelopment and testing
pai_test_* key ──> api-staging.pyramid-ai.com ──> Staging database
pai_live_* key ──> api.pyramid-ai.com ──────────> Production database

These environments are completely isolated. They share no data — a document uploaded to staging doesn’t exist in production, and vice versa.

Why two environments?

Staging exists so you can experiment without consequences. Upload test documents, create dummy projects, run compliance checks — nothing you do in staging affects real client data.

Use staging when…Use production when…
Building a new integrationIntegration is tested and ready
Testing upload flowsServing real end-users
Developing mobile app featuresMobile app is in production
Running automated tests in CI/CDLive client-facing workflows
Training new team members on the APIData matters and must persist

Key-environment enforcement

Keys are locked to their environment. This prevents accidents:

KeyUsed onResult
pai_test_*api-staging.pyramid-ai.comWorks
pai_test_*api.pyramid-ai.com401 Unauthorized
pai_live_*api.pyramid-ai.comWorks
pai_live_*api-staging.pyramid-ai.com401 Unauthorized

The error message intentionally does not tell you whether the key is valid — it simply says Unauthorized. This prevents leaking information about which keys exist.

1

Develop with staging

Use pai_test_* keys against api-staging.pyramid-ai.com. Upload test documents, experiment freely.

2

Test in CI/CD with staging

Automated tests should use pai_test_* keys. Never use production keys in test pipelines.

3

Go live with production

Switch to pai_live_* keys and api.pyramid-ai.com when your integration is ready.

Managing keys

Where to get keys

API keys are managed in the Pyramid platform under Settings > API Keys. Organization admins can create, view, and revoke keys.

Key format

Keys are 40 characters: a 9-character prefix + 32 random characters.

pai_live_7fK3aBxxxxxxxxxxxxxxxxxxxxQ2z
|________|________________________________|
 prefix          32 random characters

Key display

After creation, the full key is shown exactly once. After that, only a fingerprint is visible:

pai_live_...Q2z

This fingerprint is safe to use in logs, dashboards, and support tickets.

Key lifecycle

active ──(rotate)──> rotated (24h grace) ──> inactive
  │
  ├──(revoke)──> revoked (immediate)
  │
  └──(expires)──> expired (automatic)
  • Rotate — generates a new key. The old key works for 24 more hours, giving you time to update your integration
  • Revoke — immediately stops the key from working
  • Expire — if an expiry date was set, the key stops working automatically

Best practices

  • One key per integration — if your Excel add-in and mobile app both use the API, give each its own key. This way you can revoke one without affecting the other
  • Store in environment variables — never hardcode keys in source code
  • Rotate periodically — even without a suspected compromise, rotating keys limits exposure
  • Monitor last_used_at — keys that haven’t been used in months should be reviewed and potentially revoked