Credentials

Credentials are a 6-digit client reference and a client secret, issued per environment. Sandbox credentials are free, self-serve, and only ever touch staging inventory. Start there.

Sandbox, in one minute

npx firsty init

The CLI claims a fresh sandbox credential, stores it at $XDG_CONFIG_HOME/firsty/config.json (which defaults to ~/.config/firsty/config.json), and verifies the new credential with a live catalog call. That's it. firsty esim order works immediately.

Prefer your coding agent to do the whole setup? Paste the prompt from the top of the documentation overview. It reads agents.md and runs the same flow.

Using the credentials directly

The CLI is optional. Once you have a credential pair, anything that can make an HTTP call can use it:

export FIRSTY_CLIENT_ID="123456"        # your 6-digit client reference
export FIRSTY_CLIENT_SECRET="csk_..."   # sandbox secrets carry this prefix

Exchange them for a bearer token as shown in Authentication, or shortcut with firsty auth token.

Keep the secret out of client code and version control. It is shown once at claim time and stored only on your machine.

Going live

Sandbox credentials cannot be upgraded. Production access starts with a conversation. Talk to sales to activate a live account; you'll receive production credentials for connect.firsty.app with your commercial catalogue attached.