Authentication & scopes

Sending your key

Every route under /api/v1/partner/... and /api/v2/public/... requires a tenant-scoped API key. Send it as X-Api-Key: <key>, or as Authorization: Bearer <key> — not both on the same request, and each header at most once.

curl https://api.kwiikpay.io/api/v1/partner/me -H "X-Api-Key: kp_live_..."

Key anatomy

A key is kp_<environment>_<16 lowercase hex>.<secret> — for example kp_live_0123456789abcdef.5m3xQ…. The part before the dot is the prefix: it is stored in clear, returned by GET /api/v1/partner/me as api_key_prefix, and safe to log or quote to support. The secret after the dot is shown once, at creation, and never again. The environment segment records the environment the key was minted in: live (Production), sandbox, test, dev, or key when minted outside a known environment. What is enforced is the environment recorded on the key, not the segment string: a key minted for one environment is refused by another with a plain 401, and a key with no environment recorded works in all of them.

Headers this surface reads, and one it refuses

There are no X-RateLimit-* headers.

Server-to-server only

The partner surface is not for browsers. Cross-origin requests are allowed only from origins Kwiikpay has explicitly allowlisted (the Kwiikpay dashboard); any other browser origin fails at the CORS preflight with no API-level error. Never ship an API key to a browser or a mobile app — call this API from your own backend.

Scopes

Each key carries one or more scopes. A route requires every scope listed under security in the reference (usually one); a key missing any of them gets 403 api_key_not_authorized. Scope names are accepted in either spelling: end-customers:read and EndCustomersRead are the same scope.

Route-to-scope matrix

Computed from the same rules the runtime applies; the reference's security block on each operation is the authority for that operation.

Customer API v1 — /api/v1/partner

Customer API v2 — /api/v2/public

Under /api/v1/partner/customers/…, any subpath not listed above defaults to onboarding:read for GET and onboarding:write otherwise. That fallback exists only inside the customer tree — the top-level v1 paths (/me, /transfer/…, /commercial-config) are matched explicitly, and anything else matches no plan at all. Scopes that can be granted but that no published operation demands: compliance:read, open-banking:read, open-banking:write, end-user-fees:write — holding them buys nothing on the published surface today.

Two umbrella scopes, and what they do not cover

transactions:read and transactions:write are accepted as shorthand when a key is created, but they are narrower than they sound, and the key stores the expanded set (so /me never shows them):

• transactions:read grants balances:read, deposits:read, withdrawals:read and exchanges:read.
• transactions:write grants withdrawals:write and exchanges:write — and nothing else.

In particular transactions:write does not grant payout-batches:write. A batch payout pays many beneficiaries in one operation, so it carries its own scope deliberately, and a key holding only the umbrella scope gets 403 on every payout-batch call. Ask for payout-batches:write by name.

What your key can reach: three bindings

A key is bound in one of three ways. GET /api/v1/partner/me reports which (subject_binding).

The 404 for "not mine" is byte-identical to "does not exist". This is deliberate: a subject-bound key cannot use response codes to enumerate other customers. If you compare a list to a by-id read and they disagree, the key's binding — not the data — is the first thing to check.

An unbound key is the trap: it authenticates, every call is 200, and every list is empty, which looks exactly like "you have no customers yet". If /me says unbound, ask Kwiikpay to reissue the key; it cannot be fixed from your side.

If you're issuing a key to an end customer of yours (for example, so their own systems can read their own balance), always use a subject-bound key scoped to just them.

To operate your own children with the parent's key, follow Sub-customers & parent access. It explains when customerId means the parent, when it means the child, and the separate onboarding eligibility requirement.

Authentication failures

All authentication failures are application/problem+json with one code per status — api_key_authentication_failed (401) or api_key_not_authorized (403). The granular reason is recorded on our side and deliberately not returned:

Rate limits

In production, the public-api policy allows 600 requests per fixed 60-second window for each API key, method and route template — GET /customers/{a} and GET /customers/{b} share one counter; GET and POST on the same path do not. The window is aligned to clock minutes, so up to twice the budget can land across a boundary. POST /api/v2/public/access-requests has its own, tighter policy.

A second, tenant-wide ceiling allows 6,000 requests per 60 seconds across all of your traffic: every API-key call on both surfaces and your dashboard sessions. A burst spread across different routes — or a colleague's dashboard use — can therefore hit the aggregate limit even when no individual route is over its own.

Failed API-key authentications have a separate ceiling: 20 failed authentications per 60 seconds per source IP, shared by everyone behind that address. A refusal after that budget returns 429 instead of 401/403, and waiting does not clear it — fix the credential. Successful calls do not consume this failure-only budget.

Every 429 carries Retry-After (whole seconds). See Errors for the wire contract.

IP allowlists and rotation

An IP address or CIDR allowlist is mandatory when a key is created. There is currently no API operation that updates an existing key's allowlist. If an egress address changes, create a replacement key with the correct allowlist, move the integration to it, and revoke the old key.

Rotation is for replacing secret material, not changing authorization. A rotation mints a new key (new prefix, new secret) and keeps the old one valid for an overlap window — 24 hours by default, up to 720 hours (30 days) — after which the old key answers 401. The replacement preserves the original scopes and IP allowlist. If either is wrong, create a correctly scoped and allowlisted key instead of rotating it. An expired key cannot be rotated. Key creation, rotation and revocation are dashboard operations; no /api/v1/partner or /api/v2/public route manages keys.

Webhook registration

/api/v2/public is a supported customer API surface, including POST /api/v2/public/webhook-subscriptions. Use webhooks:write to create or change a subscription and webhooks:read to list subscriptions and delivery attempts. A subject-bound key creates a subject-owned endpoint, so it receives only that customer's events (and any explicitly delegated child-subject events).

Registration deliberately returns 403 in three cases:

• A legacy Unbound key has no customer owner. Reissue it as a subject-bound key.
• API-key subject-binding enforcement is temporarily disabled. Registration is unavailable for that incident window; retry after enforcement is restored.
• A tenant-wide key is used in a Direct-distribution tenant. Use a subject-bound key so the endpoint is scoped to one customer.

Versioning and change

/api/v1/partner is the supported surface for money movement and /api/v2/public is its companion for reads and webhooks; neither has an announced end of life, and there is no published deprecation policy, Deprecated/Sunset header, or changelog feed yet. What you can rely on today: the documents at /openapi/v1.json and /openapi/v2public.json describe what is served, and changes to them are additive in practice (new fields, new codes). Fields you do not recognise should be ignored; codes you do not recognise should be treated as a refusal. The api_version value on webhook envelopes (2026-05-legacy) is a constant and is not a negotiation mechanism.