Developer guide · Agent API
A governed loyalty API for software agents.
The Agent API exposes scoped machine-to-machine tools for loyalty operations. It does not replace the member session API or operator interfaces.
- Authentication
- Scoped agent keys
- Discovery
- OpenAPI and tool catalogue
- Audit
- Key and action records
Short answer
Start with the caller and the allowed action.
The Reward Loyalty Agent API gives software agents and backend services scoped machine-to-machine access to loyalty operations. Each key belongs to an administrator, partner, or verified member, carries explicit scopes, and leaves audit records. Use the locale REST API for signed-in product clients and webhooks when another system needs committed events pushed to it.
Decision criteria
Choose the integration boundary.
Identity, scopes, command direction, committed events, audit, and recovery determine whether an agent integration is safe to operate.
Caller identity
Choose administrator, partner, or verified-member ownership and issue the narrowest key that can complete the workflow.
Integration direction
Use the Agent API for commands, webhooks for committed event delivery, and the locale REST API for product sessions and custom clients.
Production control
Set scopes, key storage, rate handling, idempotency, validation, logging, monitoring, and incident revocation before live writes.
API model
Start from the actor and the committed fact.
An agent should not receive broad access because its prompt sounds trustworthy.
Administrator tools
Operate installation-level resources only through keys and scopes that belong to an administrator.
Partner tools
Manage one business’s programs, staff, transactions, passes, achievements, and reports within partner scope.
Member tools
Read and act for the verified member who owns the key, without exposing another member or partner relationship.
Webhooks
Receive signed notifications after supported loyalty events commit, with delivery history and retry behavior.
Production path
Test discovery, authorization, and recovery.
A successful example call is the start of integration work.
-
1
Create a narrow key
Choose the owner and scopes for one workflow rather than granting a broad production key.
-
2
Use the generated specification
Import the current OpenAPI document or tool catalogue instead of copying stale endpoint lists into an agent prompt.
-
3
Test safe failures
Exercise invalid input, missing scope, wrong tenant, rate limits, duplicate commands, and upstream timeout behavior.
-
4
Monitor and revoke
Review audit records and service health, rotate secrets, and keep a tested revocation route for incidents.
Product and operating limits
Treat the API as a controlled tool boundary.
- The Agent API does not make an agent safe by itself. The integrator controls prompts, tool selection, confirmation, secret handling, and business authorization.
- Member, partner, and administrator keys have different scope and ownership rules. Do not use one identity as a shortcut for another.
- The current endpoint set, scopes, and tool definitions can change. Use the generated specification and maintained documentation as the source.
Implementation guides
Use current documentation for changing details.
Requirements, interfaces, settings, limits, and release behavior belong in the maintained product documentation.