Authentication

The Strimz API has two clients with very different needs: the dashboard, which runs in a merchant's browser, and your server-side code. Each has its own authentication scheme.

Dashboard sessions (Privy access tokens)

When a merchant logs in to the dashboard, Privy handles the auth flow (email, wallet, or social login). The dashboard then sends Privy's access token along with every API request:

Authorization: Bearer <privy-access-token>

The Strimz API verifies the token with Privy's server-side library, finds the merchant by privyUserId, and attaches them to the request. The very first time a new merchant logs in, you'll see a merchant_not_synced error. The dashboard handles this automatically by calling POST /v1/auth/sync to create the merchant row, then retrying the original request.

You usually don't need to think about any of this. If you're building a custom admin tool, the browser SDK handles the token round-trip for you.

SDK requests (API keys)

Every server-side integration uses a Strimz API key:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keys come in two kinds and two modes:

Secret keys must never reach the browser. If GitGuardian or our own scanner spots one in a public source, Strimz rotates it automatically. You get an email and the old key starts returning 401s.

Publishable keys are scoped to read-only methods and the create-session endpoint, so they're safe in the browser. The browser SDK uses them so your server doesn't have to round-trip every checkout intent.

Scopes

Every secret key has a scope list. When you issue a new key from the dashboard, you tick the actions it can take. The API enforces the list on every request. If your key has subscriptions_read but tries to call POST /v1/subscriptions/{id}/cancel, you'll get a permission_denied error.

Available scopes (underscore-separated, alphabetical):

agents_read           agents_write
api_keys_read         api_keys_write
customers_read        customers_write
invoices_read         invoices_write
refunds_read          refunds_write
sessions_read         sessions_write
storefronts_read      storefronts_write
subscriptions_read    subscriptions_write
transactions_read     transactions_write
webhooks_read         webhooks_write

The dashboard offers preset scope bundles ("read-only", "checkout-only", "full") so you don't have to tick eighteen boxes for every key. You can always issue a more permissive key later and revoke the narrow one.

Live-mode eligibility

You can't issue a live-mode key the moment you sign up. Live-mode unlocks once you've completed:

1. Email verification. Privy verifies your email address.
2. Two-factor authentication. Enabled in your Privy account settings.
3. Business onboarding. The self-attested form in the dashboard (business name, sector, country, payout address).

The dashboard checks GET /v1/merchants/me/live-mode-eligibility, which returns structured reasons so the UI can point you at the right step. There is no manual review queue on the basic plan. The key unlocks the moment all three checks pass.

Rotating a key

Revoke and re-issue at any time. The old key starts returning authentication_error immediately. Strimz never hard-deletes a key; it stays in your audit log as revoked so you can prove later when it stopped working.

await strimz.apiKeys.revoke('mak_xyz')
const newKey = await strimz.apiKeys.create({ name: 'production', scopes: [...], mode: 'live' })
console.log(newKey.secret)  // shown once

If a key is exposed in a public repo, contact security. Strimz auto-revokes it and audits usage from the leak window.