Skip to main content
Send an API key as a bearer token on each request:
API access must be enabled for your account or agency program. A permission scope does not bypass subscription or agency restrictions. See API access.

Create a key

  1. Open Settings → Advanced → API Keys in your program.
  2. Select Generate New Key and choose Full access, Read only, or Custom permissions.
  3. Optionally set an expiry date and time. The dashboard uses your local time zone; Referly stores the absolute time in UTC. Expiry must be in the future.
  4. Generate the key, copy it, and store it in your backend’s environment variables or secret manager.
The list shows permissions and expiry status. Existing keys retain their access. Keys created without permission options default to full access (*), and without an expiry they do not expire automatically. Deleted, revoked and expired keys are rejected. Keys managed by integrations such as Zapier may be hidden from this list. Manage those through their integration connection.

Resource permissions

Scopes use resource:read and resource:write. They are independent: write permission does not imply read permission. Full access uses *; Read only includes every supported read scope. Custom permissions must include at least one permission. For example, a reporting integration can use analytics:read and balances:read. Reviewing a commission requires commissions:write. Listing group members uses groups:read; assigning members uses groups:write. GET /affiliates/{id}/balance requires balances:read. Retrieving a webhook signing secret requires webhook-endpoints:write, even though it is a GET request. Legacy endpoints also enforce their corresponding resource permissions.

Select a program

A key defaults to the program in which it was created. If that exact key provisions another program with POST /programs, operational requests can select the new program:
The creating key retains its existing scopes. Other keys do not inherit the grant, and pre-existing sibling programs are not accessible just because they share an owner. The grant stops working if the target program changes owner. Omitting the header restores the original program context. GET /programs describes the selected program, not every program in your account. Legacy affiliate, referral, sale, link, coupon and promotional-code endpoints continue to use a key belonging to their program. See program provisioning.

Authentication errors

Operational errors contain error.code, error.message and error.requestId: Legacy endpoints can return a string in error instead. See errors for both formats.

Rotate keys

Create a replacement with the required permissions, update each consumer, verify a request succeeds, then delete the old key. Deletion takes effect immediately. Provisioned-program grants belong to the exact creating key; a replacement does not inherit them. Create a key in the target program when moving those integrations to a replacement. Keep every key server-side, including read-only keys. Use a separate key for each integration so you can revoke one independently. The browser tracking script uses a public program ID and does not need an API key.
Last modified on October 23, 2026