Docs

Authentication

Merchant APIs use a secret key. Portal pages use a session cookie. Staff sign-in is separate and uses an authenticator code.

API keys

Create keys in the merchant portal under Developers → Your apps. The plaintext is shown once. Sandbox keys start with sk_test_. Live keys start with sk_live_.

Send the key as a Bearer token. Every write also needs a unique Idempotency-Key.

Authorization: Bearer sk_test_...
Idempotency-Key: 8f3c1a2e-4b90-4d11-9c0a-2e6b1d7a9f10
Content-Type: application/json

The key's environment is the environment of the checkout. A test key cannot create a live payment. Live keys cannot be issued yet, because Steadi Pay is not live. See Go live.

Who can call what

Caller	How	Used for
Your app	API key	Checkout sessions, payments, refunds, fee quotes
Customer browser	Public checkout routes	Choose a method and pay. No secret key.
Merchant staff	Session cookie	Portal: payments, developers, tickets
Steadi Pay staff	Staff sign-in + TOTP	Admin console only

Merchant portal sign-in

The portal uses a session cookie after email and password. A merchant can turn on an authenticator (TOTP) and add passkeys under Security. If authenticator is on, password sign-in asks for the 6-digit code. Sign in with passkey skips the password. Staff accounts still use password then authenticator, not passkeys.

Idempotency

POST and other writes require Idempotency-Key. Reusing a key with the same body returns the original result. Reusing it with a different body returns idempotency_key_reuse. Generate a new UUID per distinct operation.

Keep keys off the client

Create sessions from your server. Do not put sk_live_ or sk_test_ in a mobile app, a public repo or browser JavaScript.