Skip to content

Authentication and tokens

Publishable keys (pk_) for your site, API tokens (ptk_) for your server, scopes, organization pinning, CSRF and error answers.

REM Payments has four kinds of caller. Each is accepted only where it belongs.

Caller

Credential

Where it works

Your site, in the browser

Publishable key pk_... (per app, not a secret)

GET /api/public/{pk}/catalog, POST /api/public/{pk}/checkout

Your server or an agent

API token Authorization: Bearer ptk_...

Every /api/... route the token's scopes allow

The dashboard

Session cookie paymentshub_session + X-CSRFToken header

Every route (CSRF enforced)

A gateway

The provider's own signature

POST /api/webhooks/{provider}/{gateway id} only

Publishable keys

Every app has one, on the app page under Keys. It can only read the catalogue and open checkouts. It stops working when the app is inactive or the organization disabled. Restrict which browser origins may use it with the app's Allowed origins; requests without an Origin header (from a server, or curl) are not blocked by that list. Rotate it with POST /api/apps/{id}/rotate-key: the old key stops working at once.

API tokens

Made under API Tokens in the dashboard (browser session only; a token cannot mint tokens). Format ptk_ + 43 URL-safe characters; only a SHA-256 hash is stored.

A token's power is the intersection of three things: the scopes it was made with (read, write, finance, admin), what your platform role allows, and your role in the organization it touches. A token pinned to an organization sees only that organization; any other answers 403 token is pinned to another organization.

curl https://rempayments.com/api/me -H "Authorization: Bearer $PTK"
curl "https://rempayments.com/api/orgs/1/payments?status=captured" -H "Authorization: Bearer $PTK"

A request with a bearer token and no session cookie needs no CSRF token. A request with both is treated as a browser session and must send X-CSRFToken.

Scopes per role

Organization role

Scopes

viewer

read

developer

read, write

finance

read, finance

admin, owner

read, write, finance

Errors

Errors answer with an HTTP status and {"detail": "<sentence>"}, and for refusals that need a decision a machine code too. Common ones:

Status

Example

400

coupon is not valid for this plan, bad quantity, body too large

401

missing or revoked token

403

your role does not allow finance, origin not allowed for this app, organization is disabled

404

unknown publishable key, unknown plan

409

choose_how (a price change needs a plan change), plan_in_use, app_in_use, no enabled gateway accepts USD

429

sign-in rate limit

502

gateway error: ... (the provider refused; the stored session keeps last_error)

Gateway credentials and endpoint secrets are encrypted at rest and never returned in clear: the API masks them as ••••• plus the last four characters.

Last updated 18 Nov 2026

Authentication and tokens · REM Platforms Blog