Create a key
- Open Settings → Advanced → API Keys in your program.
- Select Generate New Key and choose Full access, Read only, or Custom permissions.
- 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.
- Generate the key, copy it, and store it in your backend’s environment variables or secret manager.
*), 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 useresource: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 withPOST /programs, operational requests can select the new program:
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 containerror.code, error.message and error.requestId:
Legacy endpoints can return a string in
error instead. See errors for both formats.