Skip to content

Earn 30% on every license you refer. Join the affiliate program

$349
Get it · $349 Try demo
Sign in

Enabling & managing keys.

How to create, configure, and revoke Integration API keys.

Oct 4, 2026

Administrators control which partners can use the Agent API. Partners create and revoke their own keys in the partner dashboard.

Prerequisites

Before a partner can create Integration API keys:

  1. Enable Agent API: As an administrator, open Settings → Integrations, turn on Agent API, and save. The feature is off by default.
  2. Grant the partner permission: An administrator turns on the Agent API permission for the partner (see Partner Permissions)
  3. Partner has at least one club: Most agent endpoints operate within a club context

Enabling Agent API access

As an Administrator:

  1. Navigate to Partners in the admin sidebar
  2. Open the business row to edit its account
  3. Switch to the Permissions tab
  4. In Integrations, enable Agent API
  5. Set Maximum integration API keys or turn on Unlimited
  6. Click Save

After you enable the permission, the partner sees Integration API keys under Integrations in their sidebar.

Creating a key

As a Partner:

Key forms show one Details section, with the fields together. Administrator and member key forms use the same layout.

  1. Navigate to Integrations → Integration API keys in the sidebar
  2. Click Create
  3. Fill in:
    • Name: A descriptive label (e.g., "POS Terminal Downtown", "Zapier Integration")
    • Permissions: The Partner key creation form selects View only. Choose Point of Sale for purchase and reward writes, or the management preset needed by your integration
    • Allow monetary prepaid pass writes: Leave unchecked unless the integration must manage monetary products, record external sales, spend balances, or reverse spends. Checking it adds both write:passes and write:pass-money.
    • Expiration date: Optional expiration date
  4. Click Save

One-time key display

After saving, a dialog shows the full key:

rl_agent_a8f3k2m1x9v4b7n2p5q8r1t6w3y0z4d7f0h3j6l9m2o5r8u1w4z7c0e3...

⚠️ Copy this key now. After you close this dialog, the full key never appears again. Only the prefix (rl_agent_a8f3k2m1) remains visible. If you lose the key, create a new one.

Permission level presets

The Partner key creation form selects View only by default. Selecting another preset applies to the key you are creating; existing keys retain their scopes. Monetary writes stay off until you enable their separate control.

When creating a key, you choose from these presets:

Preset Scopes Granted Use Case
View only read Dashboards, reporting, balance checks
Point of Sale read, write:transactions, write:rewards Point-of-sale earn, burn, and reward management
Full management read, write:cards, write:rewards, write:stamps, write:vouchers, write:passes, write:clubs General integrations (Zapier, Make)
Full access admin (super-scope) Complete programmatic control

The presets alone do not grant monetary pass writes, including Full access. Monetary reads use the existing read permission with pass_format=2; refund and correction actions stay in the business dashboard.

You cannot change scopes after creation. To use different scopes, create a new key.

See Scopes & Permissions for details on what each scope allows.

Viewing keys

Select What are Integration API keys? above the partner list to open its instructions. The block starts collapsed each time you load the page. You can close or reopen it at any time.

The Integration API keys list shows:

Column Description
Name Your descriptive label
Key Prefix First characters of the key (for identification in logs)
Permissions Read-only access to the scopes saved on the key, with an effective-access badge
Active Whether the key is active
Expiry Date Expiration date, or No expiry for a key with no stored end date
Last Used The key's most recent request, or Never used before its first request (the timestamp updates every 5+ minutes)
Created Creation date

Open Permissions in a list row or the edit form to inspect the saved scopes. A custom or legacy combination can differ from a creation preset. Monetary writes require both write:passes and write:pass-money. Permissions stay read-only after creation; create a replacement key for a different grant.

The badge accounts for key inactivity, expiry and an inactive owner. The Active column and switch still show the key's saved setting. Stored permission grants alone do not make an expired or inactive key usable. The prefix identifies a key in the list; the full secret still appears once, at creation.

Revoking a key

Open Integrations → Integration API keys and find the key.

  • Deactivate: Click Edit, turn Active off, and save. The key stays in the list and returns AUTH_KEY_REVOKED. Turn it on again to restore access.
  • Delete: Click Delete and confirm. This removes the key. Requests then return AUTH_INVALID_KEY. If you delete it in error, create a replacement and update the integration.

Update every integration that uses the key before deleting it. API key rotation is separate from the server APP_KEY recovery rules in the production checklist.

Key rotation strategy

For security-critical integrations, rotate keys on a schedule:

  1. Create a new key with the same scopes
  2. Update your integration to use the new key
  3. Verify the new key works (call GET /api/agent/v1/health)
  4. Revoke the old key

The old key keeps working until you revoke it, so rotation causes no downtime.

Member keys

Members (customers) can also create Integration API keys to access their own data from external apps and wallet integrations.

Creating a member key

  1. Sign in to the member dashboard
  2. Open the user menu and click Integration API keys
  3. Click Create
  4. Choose a name and permission preset
  5. Copy the key from the one-time display dialog

Member key differences

Aspect Partner Keys Member Keys
Prefix rl_agent_ rl_member_
Default expiration None (permanent) 90 days
Max keys Admin-configurable (default 5) Fixed at 3
Export Available Not available
Scopes 4 presets 2 presets
Rate limit setting Configurable (default 60 RPM, max 1,000) Not shown (uses the default 60 RPM)

Member permission presets

Preset Scopes Use Case
View only read Balance checks, browsing rewards
Full access read, write:redeem, write:profile Reward eligibility, saved cards, and profile updates

Restrictions

  • Anonymous members cannot create keys: Only verified members with an email address can access Integration API key management
  • 90-day default expiration: Member keys expire after 90 days by default. Members can set a custom date, but the system enforces a default for consumer-facing key security

Limits

Partner keys: Administrators can set how many keys each partner can create via Maximum integration API keys in Partner Permissions. Select Unlimited to remove the limit.

Member keys: Fixed at 3 keys per member. This is not configurable.

Optional server configuration

The installation operator can set FEATURE_AGENT_API=true in .env as the server default, then run php artisan config:clear. The saved setting in Settings → Integrations takes precedence.