Enabling & managing keys.

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 agent keys:

1. Enable the feature flag: Add FEATURE_AGENT_API=true to your .env file. The Agent API 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. Click on the partner's name to edit their account
3. Switch to the Permissions tab
4. Enable the Agent API permission
5. Set an Agent Keys Limit if you want one (how many keys this partner can create; -1 for unlimited)
6. Click Save

After you enable the permission, the partner sees Agent Keys under Integrations in their sidebar.

Creating a key

As a Partner:

1. Navigate to Integrations → Agent Keys in the sidebar
2. Click Create
3. Fill in:
   • Name: A descriptive label (e.g., "POS Terminal Downtown", "Zapier Integration")
   • Scopes: Choose a permission level preset
   • Expires At: 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

When creating a key, you choose from these presets:

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

The Agent Keys list shows:

Revoking a key

To revoke a key:

1. Navigate to Integrations → Agent Keys
2. Find the key in the list
3. Click Delete to remove it for good, or click Edit and toggle Active off to deactivate it (reversible)
4. Confirm the action

What happens when you revoke a key:

• Every request with that key receives AUTH_KEY_REVOKED (401) from that moment
• The key record remains in the database for audit trail purposes
• Existing activity log entries for that key stay in place
• Any integration using this key needs a new key

⚠️ Revoking is immediate and irreversible. If you revoke a production key by mistake, create a new one and update your integration.

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 agent 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 Agent Keys
3. Click Create
4. Choose a name and permission preset
5. Copy the key from the one-time display dialog

Member key differences

Member permission presets

Restrictions

• Anonymous members cannot create keys: Only verified members with an email address can access agent 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 Agent Keys Limit in Partner Permissions. A value of -1 means unlimited.

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

Related topics

• Authentication: How keys authenticate requests
• Scopes & Permissions: What each scope allows
• Partner Permissions: Admin controls for partner access
• Audit Logging: Monitor key usage