Getting Started.

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.

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. Enable FEATURE_AGENT_API=true.
2. For partner integrations, enable the partner's Agent API permission in the admin UI.
3. Create the key in the relevant dashboard area.

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

{
  "error": true,
  "code": "FEATURE_DISABLED",
  "message": "Agent API access is not enabled for this partner.",
  "retry_strategy": "contact_support"
}

3. Store the Key Correctly

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

Important facts:

• The role prefix is part of the raw key: rl_agent_, rl_member_, or rl_admin_.
• The random secret portion is 40 characters.
• The full key is shown once at creation time.
• The full key is never recoverable later. If lost, 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 successfully
• the role is correct
• the scopes match your integration
• the rate limit is appropriate

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:

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:

See Scopes & Permissions for the exact endpoint matrix.

Next Steps

• Tool Discovery — Let your agent discover available tools at runtime
• OpenAPI Spec — Browse the interactive API documentation
• POS Integration
• E-commerce Guide
• Common Workflows
• Production Checklist
• Authentication
• Managing Keys