Skip to content

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

$349
Get it · $349 Try demo
Sign in

Getting started.

Make your first authenticated Agent API call and choose the right key model for your integration.

Oct 4, 2026

This guide gets a new integration from zero to its first successful request. It focuses on the real production contract: key prefixes, header format, response envelopes, and the first checks an integration should make before it starts awarding points or redeeming rewards.

1. Choose the right key type

Use the narrowest key that matches the job.

Key Type Prefix Use It For
Partner key rl_agent_ POS systems, e-commerce writebacks, back-office automations
Member key rl_member_ Wallet views, member reward browsing, reward eligibility checks
Admin key rl_admin_ Platform administration, partner oversight, analytics

If your system needs to perform financial or loyalty-program operations on behalf of a business, use a partner key. If it needs to read or update only one member's own wallet, use a member key. Do not use a partner key where a member key is sufficient.

2. Enable the feature

The Agent API is feature-gated.

  1. As an administrator, open Settings → Integrations, turn on Agent API, and save.
  2. For partner integrations, enable the partner's Agent API permission in the admin UI.
  3. Create the key in the relevant dashboard area. The Partner key creation form selects View only by default. Choose Point of Sale explicitly for purchase and reward writes, or a management preset for other writes.

If the feature is disabled for a partner, partner endpoints return:

{
  "error": true,
  "code": "FEATURE_DISABLED",
  "message": "Agent API access has been revoked for this partner.",
  "retry_strategy": "contact_support"
}

3. Store and send the key

Every request sends the key in the X-Agent-Key header.

X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0
X-Agent-Key: rl_member_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8
X-Agent-Key: rl_admin_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

What to know:

  • The role prefix is part of the raw key: rl_agent_, rl_member_, or rl_admin_.
  • The random secret portion is 40 characters.
  • The dashboard shows the full key once, at creation.
  • The full key is never recoverable. If you lose it, create a new key and revoke the old one.

4. Make a health check first

Before calling any business endpoint, call GET /api/agent/v1/health.

GET /api/agent/v1/health HTTP/1.1
Host: your-domain.com
Accept: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

Successful response:

{
  "error": false,
  "data": {
    "status": "ok",
    "key": {
      "name": "POS Terminal 1",
      "prefix": "rl_agent_A1b2C3d4",
      "role": "partner",
      "scopes": ["read", "write:transactions", "write:rewards"],
      "rate_limit": 60,
      "expires_at": null,
      "created_at": "2026-03-08T16:00:00+00:00",
      "last_used_at": "2026-03-08T16:10:00+00:00"
    },
    "owner": {
      "id": "019cce5d-bd7e-73ec-b4ce-9dc6f7f73ed8",
      "name": "Coffee Corner",
      "type": "partner"
    }
  }
}

Use this response to verify:

  • the key authenticates
  • the role is correct
  • the scopes match your integration
  • the rate limit fits your traffic

5. Understand the core response pattern

Success responses use a stable JSON envelope:

{
  "error": false,
  "data": {
    "id": "resource-id"
  }
}

Paginated responses add a pagination object:

{
  "error": false,
  "data": [],
  "pagination": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 81
  }
}

Default pagination behavior:

  • per_page defaults to 25
  • per_page is capped at 100

Locale conventions:

  • Resource fields such as member locale use installed locale codes like en_US or fr_FR
  • The Accept-Language header uses normal HTTP language tags such as en-US or fr-FR

6. Handle errors by retry_strategy

All errors are machine-readable.

{
  "error": true,
  "code": "AUTH_INSUFFICIENT_SCOPE",
  "message": "This key does not have the required scope.",
  "retry_strategy": "no_retry",
  "details": {
    "required_scope": "write:transactions"
  }
}

Use retry_strategy to decide what to do:

Strategy Meaning
no_retry Permanent failure for this request
fix_request Correct the payload and send again
backoff Temporary problem such as rate limiting
contact_support Human action required

See Error Handling for the full matrix.

7. Choose scopes before you ship

Do not create broad keys by default. Start from the smallest useful scope set.

Typical starting points:

Integration Recommended Scopes
POS earn + redeem read, write:transactions, write:rewards
POS with stamps read, write:transactions, write:rewards, write:stamps
Voucher-enabled checkout read, write:vouchers
Member wallet read or read, write:profile, write:redeem

See Scopes & Permissions for the exact endpoint matrix.

Optional server configuration

The installation operator can set FEATURE_AGENT_API=true in .env and run php artisan config:clear. This sets the default; a saved dashboard setting takes precedence.

Next steps