API keys

Keys are created in the dashboard, under API keys, by an owner or admin. Each key belongs to one project and one environment: a sandbox key never sees production data.

Three kinds

Public keys (rp_pub_) go in your app. They can only call the /v1/sdk routes.
Secret keys (rp_sk_) stay on your server and can do everything in their project and environment.
Restricted keys are secret keys that can do only what you choose. Use one for anything that does not need everything: a reporting job, a support tool, an AI agent.

What a restricted key can be given

For each area you choose nothing, read, or read and write. Anything you leave out is refused.

Area	Read	Write adds
`customers`	Customers and their referral codes	Create or update a customer
`referrals`	Referrals, timelines, the referrals export	Void a referral
`rewards`	Rewards, the rewards export	Void a reward
`programs`	Programs, reward definitions, offer code pools	Create and change them
`screens`	Screens, placements, templates	Edit, publish and roll back
`analytics`	The funnel, charts and setup status	Nothing to write
`webhooks`	Webhook endpoints and delivery logs	Create, change, delete, redeliver
`events`	Nothing to read	Report a purchase

Moving money is separate

Approving a reward, granting one by hand and resending one need write access to rewards and the "Can move money" switch, which is off unless you turn it on. Voiding does not need it, because voiding only stops money.

Reporting a purchase is not moving money, but it can lead to it: a purchase can qualify a referral, and a program with no approval step then sends its rewards. Give events only to the system that really reports your purchases.

Good to know

A key's permissions are chosen when it is created and never change. To change them, create a new key and revoke the old one.
Restricted keys cannot call the SDK routes. Use a public key in your app.
A refused request answers 403 with the code insufficient_permissions, and the message names what was missing.
GET /v1/ping works with any secret key and returns its permissions, so a tool can check what it was given:

{
  "project_id": "…",
  "environment": "production",
  "key_type": "secret",
  "permissions": {
    "resources": { "referrals": "read", "rewards": "read" },
    "money": false
  }
}

For a full-access key permissions is null.