Environments and API keys

An organisation holds any number of environments. Each one is a separate world: its own API keys, provider connections, routing policy, webhook endpoints, and every customer, account, link session, quote, payment intent and event created in it.

Organisation
├── secret sources (your Infisical project)        shared by every environment
└── environments
    ├── sandbox      mode test
    ├── staging      mode test     (optional, name as many as you like)
    └── production   mode live
        ├── API keys            ur_live_sk_…
        ├── provider connections
        ├── routing policy
        └── webhook endpoints

New organisations start with sandbox (test) and production (live). Add more when you need them, for example a staging environment in test mode that your staging deployment uses.

Test and live modeCopy Anchor Link

An environment's mode decides which provider environments its connections may use. Test environments accept only provider sandboxes and live environments accept only production, and Unirail checks this when you create the connection, so a misconfiguration fails at setup rather than on a payment.

API keysCopy Anchor Link

Secret keys are shown once when you create them and stored only as a hash; the dashboard keeps the prefix so you can tell them apart. A key can carry scopes and an expiry, and you can revoke it at any time.

The key's environment, not a parameter, decides where a call runs. A test key can never read or write live data, and a live key can never touch test data. The SDK can tell you which one you hold:

import { keyMode } from "@unirail/sdk";

keyMode(process.env.UNIRAIL_SECRET_KEY!); // "test" | "live" | undefined

Keep secret keys in your own secrets manager and never ship them to a browser or an app.

Request headersCopy Anchor Link

API versionsCopy Anchor Link

The API is versioned by date, sent in the Unirail-Version header. The SDK sends the version it was built against unless you pin another:

const unirail = createUnirail({ apiKey, version: "2026-10-08" });

The current version is 2026-10-08. The changelog lists what each version changed.