Partner API
Authentication
Authenticate to the RobinReturn Partner API with a bearer API key, and the scopes each endpoint requires.
Last updated
Authenticate every request with your API key, sent as a bearer token:
Authorization: Bearer rr_live_xxxxxxxxxxxxxxxxxxxxxxxxTo check a key works, read a case. A 401 means the key itself was refused, a 403 that it lacks
the cases:read scope, and a 404 that the key is valid but no case of yours has that id:
curl -i https://app.robinreturn.co.uk/api/v1/cases/REPLACE_WITH_CASE_ID \
-H "Authorization: Bearer $RR_API_KEY"The X-Api-Key: rr_live_… header is also accepted. A missing, malformed, unknown or revoked key
returns 401. A key without the scope a route requires returns 403.
Scopes
A key is granted only the scopes you requested at access time.
| Scope | Grants |
|---|---|
cases:write | Upload invoices and create cases (POST /api/v1/uploads, POST /api/v1/cases) |
cases:read | Read case status (GET /api/v1/cases/{id}) |
webhooks:manage | Reserved for webhook management. Endpoints are registered in the dashboard rather than through the Partner API, so this scope grants no API call today — see Webhooks |
Keeping keys safe
- The full secret is shown once at creation — store it in a secret manager, never in source control or a client-side bundle.
- A key creates cases in your company's name, each carrying an eligibility attestation, and reads their status. It cannot start chasing or take a payment, but treat it like a production credential.
- Revoke a key immediately if it may have been exposed, and mint a replacement.
- Keys are per-company; all access is scoped to your own company's data.