Authentication

Firmly supports two authentication models. Pick the one that matches where your code runs.

• Browser session (most common) — client-side code (browser, mobile app, ad surface, embed) bootstraps a session by sending your App ID in the x-firmly-app-id header to POST /api/v1/browser-session. That call returns a short-lived JWT access_token.
• Server-to-server (S2S) — backend services (banks, wallets, autonomous agents) authenticate with a Firmly-issued secret instead of a per-buyer JWT, paired with an x-firmly-device-id for cart isolation.

On every authenticated call afterward, pass the credential in the x-firmly-authorization header — the browser-session JWT for the browser model, or the S2S secret for the server-to-server model.

The base URL is https://api.firmly.work (payment calls use https://cc.firmly.work — see Base URLs). Those are the sandbox hosts — production uses different ones, provided at go-live. Your App ID and the merchant domain you call determine which merchants you can reach.

• Browser Session
• Server-to-Server Authentication