Reward Networks Reward Networks Developer Hub

Account & API keys

Developer account

  1. Register at /docs/register with your name, email and password.
  2. Approval. New accounts are reviewed by the Reward Networks team. Until then you can read the docs but cannot sign in.
  3. Sandbox. On approval a sandbox merchant is provisioned for you automatically and linked to your account. See Sandbox.
  4. Live merchants. The merchant decides who may access their store. In the Developer Portal → Merchant access, search the merchant by brand name or, better, by the Merchant ID the owner sees on their Settings → Integrations page (#123) or by their account email (exact match only), tick the scopes you need, add a short message and send the request. The store owner sees it under Settings → Integrations in their dashboard and approves (possibly with fewer scopes) or rejects. Once approved the merchant appears in your Create key dropdown. The owner can revoke access at any time; all your keys for that store stop working immediately.

Ask for the smallest set of scopes that does the job. A POS needs transactions.write and customers.read; a reporting tool needs only history.read. Owners approve narrow requests faster, and a key can never carry more than the owner granted.

API keys

Keys are created, rotated and revoked by you in the Developer Portal. Each key:

Property Meaning
Merchant Every key is bound to exactly one merchant. Every request made with it acts as that merchant.
Mode rn_test_… keys are issued for the sandbox merchant, rn_live_… keys for real ones. The mode follows the merchant; you do not choose it.
Scopes Optional. Restrict the key to some of transactions.write, members.write, customers.read, catalog.read, history.read. No scopes = full access. See scopes.
Expiry Optional. An expired key answers 401 API key expired.
Rate limit 120 requests/minute by default, configurable per key by the Reward Networks team.

The plaintext key is shown once, at creation. Store it in your POS configuration, not in source control.

Sending the key

Authorization: Bearer rn_live_abc123...
Accept: application/json

Rotate

Rotate issues a replacement and revokes the old key in the same step. The old key stops working immediately, so deploy the new value first if you need zero downtime: create a second key, switch your POS to it, then revoke the first.

Revoke

Revoked keys answer 401 forever. Revoking is idempotent.

Multiple merchants or branches

One key per merchant. If you serve several merchants, you hold several keys and pick one per request. Branches within a merchant are chosen per request with branch_id — list them with GET /branches.

Errors you will see during setup

Status Message Cause
401 (no body) Missing, unknown or revoked key.
401 API key expired Key past its expires_at. Create a new one.
403 Developer account is not active. Your account was deactivated. Contact the team.
403 This API key does not have the required \history.read` scope.` Key scopes exclude this endpoint.
403 Test key on a live merchant (or vice versa) Key mode does not match the merchant.