Security and keys

Perkamo separates trusted backend operations from browser or mobile integration work. Server API keys can write events, read profiles, redeem rewards and upload config depending on scopes. Browser clients must never receive server API keys.

Server API keys

Store server keys only in backend environment variables or a secrets manager.

Create, rotate and revoke keys in Secret keys.

PERKAMO_SPACE=commerce-live
PERKAMO_SECRET_KEY=sk_live_...

Create one key per integration when possible. Rotation and revocation are safer when checkout, CRM sync and reporting do not share a single key.

Scopes

Server keys can be scoped to:

Browser-token boundary

Do not bundle server API keys in browser, mobile or widget code. The current stable public v1 API is backend-first. Browser-token key metadata and allowed request origins can be configured in the console, but client-safe /v1/client/* routes and profile stream token verification are preview work, not stable v1 API surface.

Until that flow is enabled for a customer integration, keep browser apps behind your own backend. Your backend verifies the user's session, calls Perkamo with a server key and returns only the state your UI needs.

Browser request origins are configured in Perkamo as exact origins:

• https://app.example.com
• https://shop.example.com
• http://localhost:3000 for local development

Manage allowed origins in Browser SDK.

Do not enter CSP directives, paths or wildcard domains into allowed request origins. CSP remains a header on your own website:

Content-Security-Policy: connect-src 'self' https://api.perkamo.com;

Data minimization

Send only facts Perkamo needs for rules, audit and support. Avoid card data, passwords, authentication tokens and unnecessary personal data.

Retry safety

• Retry network failures, timeouts and 5xx with the same transaction id.
• Do not retry 400, 401 or 403 automatically.
• Use exponential backoff for 429.
• Treat duplicate: true as a successful replay.