Admin Endpoints.
Platform administration via the Agent API — partner management, member search, and analytics.
Admin Endpoints
Admin agent keys give platform administrators programmatic access to manage partners, view cross-platform member data, and pull analytics — ideal for CRM integrations, SaaS billing dashboards, and monitoring tools.
Base URL
/api/agent/v1/admin/
All endpoints require an admin-type agent key (rl_admin_***).
Partners
List Partners
GET /api/agent/v1/admin/partners
Scope: read:partners
| Parameter | Type | Description |
|---|---|---|
is_active |
boolean | Filter by active status |
search |
string | Search by name or email |
per_page |
integer | Results per page (1–100, default 25) |
page |
integer | Page number |
Response:
{
"error": false,
"data": [
{
"id": "uuid",
"name": "Coffee Corner",
"email": "[email protected]",
"locale": "en_US",
"currency": "USD",
"time_zone": "America/New_York",
"is_active": true,
"avatar": null,
"created_at": "2026-01-15T10:00:00Z"
}
],
"pagination": {
"current_page": 1,
"last_page": 3,
"per_page": 25,
"total": 72
}
}
Show Partner
GET /api/agent/v1/admin/partners/{id}
Scope: read:partners
Returns the partner profile along with their permissions and usage counts.
{
"error": false,
"data": {
"id": "uuid",
"name": "Coffee Corner",
"email": "[email protected]",
"is_active": true,
"permissions": {
"loyalty_cards_permission": true,
"loyalty_cards_limit": -1,
"stamp_cards_permission": true,
"stamp_cards_limit": -1,
"vouchers_permission": true,
"agent_api_permission": true,
"agent_keys_limit": 10
},
"usage": {
"loyalty_cards": 3,
"stamp_cards": 1,
"vouchers": 5,
"rewards": 8,
"staff_members": 2
}
}
}
Update Permissions
PATCH /api/agent/v1/admin/partners/{id}/permissions
Scope: write:partners
Update a partner's feature permissions and usage limits. Great for SaaS billing tier changes.
| Field | Type | Description |
|---|---|---|
loyalty_cards_permission |
boolean | Whether partner can create loyalty cards |
loyalty_cards_limit |
integer | Max loyalty cards (-1 = unlimited) |
stamp_cards_permission |
boolean | Whether partner can create stamp cards |
stamp_cards_limit |
integer | Max stamp cards (-1 = unlimited) |
vouchers_permission |
boolean | Whether partner can create vouchers |
vouchers_limit |
integer | Max vouchers (-1 = unlimited) |
rewards_limit |
integer | Max rewards (-1 = unlimited) |
staff_members_limit |
integer | Max staff members (-1 = unlimited) |
email_campaigns_permission |
boolean | Whether partner can send email campaigns |
agent_api_permission |
boolean | Whether partner can create agent keys |
agent_keys_limit |
integer | Max agent keys (-1 = unlimited, default: 5) |
cards_on_homepage |
boolean | Whether partner's cards appear on the homepage |
Request:
{
"agent_api_permission": true,
"agent_keys_limit": 10,
"loyalty_cards_limit": 5
}
Activate / Deactivate Partner
POST /api/agent/v1/admin/partners/{id}/activate
POST /api/agent/v1/admin/partners/{id}/deactivate
Scope: write:partners
Toggles the partner's is_active flag. When deactivated, all of the partner's agent keys become invalid (the auth middleware checks ownerIsActive).
Members (Read-Only)
Admin member access is strictly read-only. Member lifecycle is managed through partner transactions (auto-enrollment) or member self-service.
List Members
GET /api/agent/v1/admin/members
Scope: read:members
| Parameter | Type | Description |
|---|---|---|
search |
string | Search by name, email, or unique_identifier |
is_active |
boolean | Filter by active status |
per_page |
integer | Results per page (1–100, default 25) |
Show Member
GET /api/agent/v1/admin/members/{id}
Scope: read:members
Returns member profile with all card balances.
{
"error": false,
"data": {
"id": "uuid",
"name": "Jane Doe",
"email": "[email protected]",
"unique_identifier": "846-346-383-611",
"is_active": true,
"is_anonymous": false,
"card_balances": [
{
"card_id": "uuid",
"card_title": "Coffee Rewards",
"club_name": "General",
"balance": 250,
"currency": "USD"
}
]
}
}
Analytics
Platform Overview
GET /api/agent/v1/admin/analytics/overview
Scope: read:analytics
Returns platform-wide aggregate metrics.
{
"error": false,
"data": {
"total_partners": 45,
"active_partners": 42,
"total_members": 12500,
"total_cards": 38,
"total_stamp_cards": 15,
"total_vouchers": 92,
"transactions_today": 340,
"transactions_this_week": 2100,
"transactions_this_month": 8500
}
}
Per-Partner Metrics
GET /api/agent/v1/admin/analytics/partners/{id}
Scope: read:analytics
Detailed usage breakdown for a specific partner.
{
"error": false,
"data": {
"partner_id": "uuid",
"partner_name": "Coffee Corner",
"is_active": true,
"loyalty_cards": 3,
"stamp_cards": 1,
"vouchers": 5,
"rewards": 8,
"staff_members": 2,
"total_transactions": 15420,
"transactions_today": 45,
"total_members_enrolled": 1250
}
}
Admin Scopes
| Scope | Grants |
|---|---|
read:partners |
List and view all partners |
write:partners |
Create, update, activate/deactivate partners |
read:members |
Platform-wide member search and details |
read:analytics |
Platform and per-partner analytics |
admin |
All of the above (super-scope) |
Integration Recipes
CRM Sync
# Sync partner list to CRM
GET /api/agent/v1/admin/partners?is_active=true
# Push metrics to monitoring dashboard
GET /api/agent/v1/admin/analytics/overview
SaaS Billing Tier Change
# Upgrade partner to premium tier
PATCH /api/agent/v1/admin/partners/{id}/permissions
{
"loyalty_cards_limit": -1,
"stamp_cards_limit": -1,
"vouchers_limit": -1,
"agent_api_permission": true,
"agent_keys_limit": 20
}
Member Lookup
# Find a member across all partners
GET /api/agent/v1/admin/[email protected]
# Get their card balances
GET /api/agent/v1/admin/members/{id}