Core Concepts
Agency Partners
Partner keys, client keys, the sandbox and agency webhooks for agencies running many clients.
Agencies run many clients from one account. A partner key reaches all of them, a sandbox lets you build your integration without touching real clients, and agency webhooks send every client's events to one place.
Keys
| Key | Made by | Reaches |
|---|---|---|
| Partner key | Your agency's owners and admins, in the partner portal | Every client of your agency, including clients added later. Pick the client with X-Workspace-Id or X-Client-Reference, or use the /clients endpoints |
Sandbox partner key (rr_test_) | Your agency's owners and admins | Sandbox clients only. Never a real client |
| Client key | A client's own login, on the Developers page | That client's workspace only, with workspace scopes. Never your other clients, your agency or credits. Stops working if the login is removed |
Partner keys can also have clients:read, clients:write and credits:read. Every key change and every client a partner key adds or changes is kept in your agency's key activity log, which can't be edited.
Picking a Client
Endpoints under /clients/{client} take the client's workspace ID or your own reference for it. On any other endpoint, send X-Workspace-Id or X-Client-Reference (not both). A client of another agency is never reachable: it answers like a client that doesn't exist.
POST /api/public/v1/posts HTTP/1.1
Host: app.tryredrover.com
Authorization: Bearer rr_live_...
X-Client-Reference: crm-1042
Content-Type: application/jsonSandbox
A sandbox key starts with rr_test_. It is a separate space shared by your agency's sandbox keys. Here is exactly what each call does with one:
| Call | With a sandbox key |
|---|---|
POST /clients | Checked like a live request, then saved as a sandbox client. No workspace, login or invite is created |
PATCH /clients/{client} | Changes the sandbox client only |
POST /clients/{client}/posts and /comments | Checked against the same rules as live content, scheduling lead time included, then recorded and answered as scheduled with canChange: false. Nothing is published to Reddit, nothing reaches our team and no credits are used |
GET /clients, /clients/{client} and their posts and comments | Sandbox clients and what you recorded for them, never live data |
GET /agency/credits and /clients/{client}/credits | Fixed figures with simulated: true. Credits never move |
| Webhooks | Your agency listeners get client.created and client.updated for sandbox clients, with sandbox: true and workspaceId: null. Sandbox posts and comments send no events |
Workspace endpoints (/posts, /workspace/profile and the rest) | Refused with 403: a sandbox key can't reach any real workspace |
Agency Webhooks
Create listeners with Create an Agency Webhook. They work like workspace webhooks: each has its own signing secret, every request is signed in RedRover-Signature, failed deliveries are retried and the last 30 days are in the delivery log. Your clients' own listeners never get agency events.
| Event | Sent when |
|---|---|
client.created | A client was added, by the API, in the partner portal or by our team |
client.updated | A client was renamed or its reference changed, wherever it happened. data.previous holds the old values |
credits.low | A spend took your agency's balance below its low line: your auto top-up threshold, or 320 credits when you have none. Sent once each time the line is crossed. data has balance and threshold |
client.cap_reached | A spend took a client to its monthly cap. data has cap and used |
| Every content event | post.posted, comment.failed and the rest, for every client. See Webhooks |
Every body names the client in client with its ID and your reference. client is null for agency-wide events like credits.low.
{
"id": "f1b3d5e7-9a2c-4e6f-8b1d-3f5a7c9e2b4d",
"type": "client.created",
"apiVersion": "v1",
"createdAt": "2026-11-16T10:00:02Z",
"agencyId": "6a1e3c5b-7d9f-4b2a-8c4e-0f2a4c6e8b1d",
"workspaceId": "8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21",
"client": {
"id": "8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21",
"reference": "crm-1042",
"name": "Acme Analytics"
},
"sandbox": false,
"data": {
"id": "8f14e45f-ceea-4e1a-9c2b-6d7a1c3b9e21",
"name": "Acme Analytics",
"reference": "crm-1042",
"sandbox": false,
"createdAt": "2026-11-16T10:00:00Z"
}
}