Keep your keys safe

A Platform key can create users, open orders and, with the money scopes, pay out your users' balances. Treat it like the password to a bank account.

The rules RekberPay enforces

Rule	What happens otherwise
Only a workspace key (rpe_) or a dashboard session may call /v1/enterprise/platform	A personal API key, an app device session (rpd_) or a WhatsApp session gets 403 KEY_NOT_ALLOWED. None of them has key scopes, an IP allowlist or a key id for the audit trail
A workspace key works only from your server	A request with a browser Origin or Sec-Fetch-Site header gets 403 KEY_IN_BROWSER, on every enterprise route
A key with an IP allowlist works only from those addresses	401 KEY_IP_NOT_ALLOWED
A live Platform key needs an IP allowlist approved by RekberPay	403 IP_ALLOWLIST_REQUIRED until it is approved (going live)
Every call needs the matching Platform scope	403 SCOPE_REQUIRED
Every key write needs an Idempotency-Key	400 IDEMPOTENCY_KEY_REQUIRED
A key acts with the live role of the member who made it	403 FORBIDDEN once that member's role no longer allows the scope; 401 once they leave

Checkout, claim, connect and release notice links are not credentials. Sent as Authorization: Bearer, they answer 401 INVALID_TOKEN.

1. Choose the scopes

A key needs read (and write for any change), plus the Platform scopes for what it does. RekberPay sets which Platform scopes your workspace may hold; see allowed_scopes in GET /v1/enterprise/platform/settings.

Scope	Allows	Role of the member who makes the key
users	Create, link, read, change and unlink users; claim links	operator or higher
orders	Deals, checkout links, ship, extend, disputes and evidence	operator or higher
kyc	Submit and read KYC	operator or higher
orders:confirm	Confirm receipt for the buyer (the release waits 6 hours). Off by default; RekberPay must allow it	finance or higher
balance:read	Read balances	finance or higher
withdraw	Bank accounts and withdrawals	finance or higher
ratings	Rate finished orders for the buyer or the seller, read order ratings. On by default for new keys	operator or higher

A new key gets ratings ticked; orders:confirm and withdraw start unticked. A key keeps the scopes it was made with: one made before ratings existed does not gain ratings, so make a new key to rate (Ratings).

Split your integration by job. For example, an order service with users and orders, and a separate payout service with balance:read and withdraw. A leaked order key then cannot touch money.

Each key has its own Platform rate limits, but all keys made by one member share that member's 300 requests a minute. For high volume, make the keys of busy services from different members.

2. Create the key in the dashboard

An admin or owner creates keys from a dashboard session, in Developers, or with POST /v1/enterprise/api-keys:

curl -X POST https://api.rekberpay.com/v1/enterprise/api-keys \
  -b cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "X-Enterprise-Account: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Order service",
    "scopes": ["read", "write", "users", "orders"],
    "allowed_ips": ["203.0.113.10", "198.51.100.0/24"]
  }'

• The key (rpe_...) is shown once. Put it in your secret manager at once.
• A Platform scope that your terms do not allow answers 400 SCOPE_NOT_ALLOWED, and so does any Platform scope after RekberPay switched Platform off for your workspace.
• allowed_ips takes up to 20 IPv4 or IPv6 addresses or CIDR ranges. On a Live key with a Platform scope the list goes to RekberPay for review: the key is created with allowed_ips: null and allowed_ips_status: "pending", and the list becomes active once approved. A Sandbox key (rpe_test_) takes the list at once and needs no review, and so does a key without Platform scopes; leave it out to allow any address.
• Keys never manage keys, members, settings or webhooks. A workspace holds at most 10 active keys per mode: 10 rpe_test_ and 10 rpe_live_.

Going live: get your IPs approved

A Live Platform key (rpe_live_) only works with an IP allowlist that RekberPay approved. Until then every Platform call with that key answers 403 IP_ALLOWLIST_REQUIRED. Sandbox keys (rpe_test_) have no such requirement.

1. In the dashboard, open Developers, pick the key and enter the public IPs (or CIDR ranges) your servers call RekberPay from. Use a fixed outbound IP or NAT gateway; domain names are not accepted. Send it.
2. The key shows Pending review (allowed_ips_status: "pending", the list in allowed_ips_pending). RekberPay is told, and so are your workspace admins.
3. A RekberPay superadmin approves it (the list becomes allowed_ips, allowed_ips_approved_at is set) or rejects it with a reason (allowed_ips_status: "rejected", the reason in allowed_ips_review_note). You get a notification either way.
4. Calls from an address outside the approved list answer 401 KEY_IP_NOT_ALLOWED.

Every later change is a new request. While it waits, the list approved before stays active, so moving servers does not cut you off: add the new IPs next to the old ones, wait for approval, move, then send a list without the old ones. An empty list is not accepted for a Platform key.

Keys without Platform scopes (B2B) keep the optional allowlist you edit yourself, effective at once (API keys).

3. Keep it on your server

• Call RekberPay only from your backend. Never put a key in a web page, a mobile app, a browser extension or a public repository.
• Your app talks to your backend; your backend talks to RekberPay. Send buyers the checkout URL, never anything that holds the key.
• Read the key from the environment or a secret manager, never from source code.
• Do not log Authorization headers, checkout URLs or claim links.

4. Rotate and revoke

Workspace keys do not expire. Rotate them on a schedule and whenever someone who knew a key leaves:

1. Create a new key with the same scopes and IP allowlist. In live mode, wait until RekberPay approved its list.
2. Deploy it to your servers.
3. Check last_used_at of the old key in GET /v1/enterprise/api-keys. When it stops moving, revoke the old key with DELETE /v1/enterprise/api-keys/:id. It stops working at once.

Removing a member also revokes every key they created, for good. Create keys from a member account that will stay, not from someone likely to leave.

If a key leaks

1. Revoke it at once in the dashboard.
2. Tell your RekberPay account manager. RekberPay can freeze your Platform access: every call then answers 423 PLATFORM_FROZEN, and no automatic or pending release and no new withdrawal goes through until it is unfrozen. A buyer can still confirm (which releases at once) or dispute on RekberPay.
3. Read your event feed (GET /v1/enterprise/events) for calls you did not make. Every Platform write is recorded with the key id.

Two safeguards already limit the damage: a new payout bank account cannot be used for 24 hours, and a release you confirm waits 6 hours while the buyer is told.

What RekberPay defends, and what stays with you

Risk	What stops it
Another partner reads your users, orders or balances	Every query is limited to your workspace. Anything outside it answers 404, never 403
A stolen key confirms orders to release money	orders:confirm is off by default. Your confirm waits 6 hours, the buyer is told and can dispute, and RekberPay staff are alerted to unusual patterns and can freeze you
A stolen key drains balances	The withdraw scope, a name check, a 24 hour cooling-off on new bank accounts, the usual limits and fraud screening, and a second approver on large amounts. Only partner funds, unless the user allowed their whole balance
A key ends up in a web page or an app	Requests with a browser Origin or Sec-Fetch-Site header answer 403 KEY_IN_BROWSER. Buyers and sellers only ever hold checkout, claim, connect and release notice links, and none of them works as a key
A checkout link is reused or changed	The link is tied to one milestone, its amount and an expiry, and works once a payment has started
Someone claims or takes over another person's account	A known email never links without the person confirming from the address on file. A claim needs a code sent to that address
A partner reaches a RekberPay staff account	A staff, blocked or closing account gets the same pending_consent request as any known email, with the same answers to a repeat POST and to GET, but it is never emailed and never accepted, so it never turns active. A user who becomes staff loses every active link; a pending request stays pending, the same as before
Someone uses RekberPay to flood an inbox	Live link requests and email changes are capped each day per user, per partner and address, and per address across all partners (429 MAIL_LIMIT_REACHED); one partner using up its own limit does not block other partners, and a person who declined is not asked again for 7 days (429 USER_DECLINED_RECENTLY)
A sandbox key makes real, verified accounts	A sandbox claim and a sandbox KYC are simulations kept apart from the account: no password, no session, never KYC verified on RekberPay, and a live link can never claim the account later
You learn what a linked person does elsewhere	limits on a user shows the caps and the room for one order now, never the person's usage across RekberPay and other partners
You probe your own old ref after that person became staff	GET answers 404, and sending the ref with another email answers 409 REF_IN_USE, like any used ref. You learn only that the ref is hidden. RekberPay accepts this
A key leaks and is used before you notice	Whatever its scopes allow, until you revoke it. Use narrow scopes, allowed_ips and the steps below

Checklist

• One key per service, with the fewest scopes that work.
• allowed_ips on every key that touches money.
• Keys only on servers, never in an app or a page.
• Rotate on a schedule; revoke on any doubt.

Next steps

• Authentication and API keys
• Enterprise API keys reference