Authentication

The Swft Partner API uses opaque bearer tokens. Provision one via the workspace dashboard (Workspace → Settings → Partner API Keys) or by calling POST /v2/workspaces/{workspaceId}/partner-keys with your Supabase JWT.

Authorization: Bearer swft_ak_live_01HZ9X...
X-Swft-Merchant: 8a1d52e0-...               (only on merchant-scoped routes)
Idempotency-Key: 4ea3...                    (required on all writes)
Swft-Version: 2026-06-01                    (optional; pinned per key)

Key prefixes

Prefix	Mode	Purpose
swft_ak_live_*	live	Production traffic. Bills real cards.
swft_ak_test_*	test	Sandbox traffic against Stripe test mode.

The prefix is shown next to the key in the dashboard and emitted in audit logs. The plaintext value is shown exactly once at creation — save it then.

Scopes

Keys carry an explicit scopes array. Defaults: merchants:read, merchants:write, webhooks:read, webhooks:write, domains:write, logs:read. A request hitting an endpoint outside its scopes gets a 403 insufficient_scope.

Versioning

Wire-format changes ship behind a new dated version. Keys are pinned to the latest version at mint time. To opt into a newer date, send Swft-Version: 2026-XX-XX on the request. Existing keys stay pinned forever unless they explicitly opt-in.

Idempotency

Every POST/PUT/PATCH on /v2/agencies/* and /v2/webhooks/* requires an Idempotency-Key header (recommendation: a v4 UUID per request).

• Same key + same body within 24h → identical response replayed.
• Same key + different body → 409 idempotency_key_reused.

Stripe-style. Safe to retry network failures.

Request IDs

Every response carries swft-request-id and traceparent headers. Capture the request id in your support tickets — it pinpoints the exact log row in GET /v2/logs/requests.