Authentication & the API
API keys, the response envelope, rate limits, idempotency and error codes — everything you need before the first request.
5 min read
The public API is versioned under /v1 and authenticated with an organization API key. Create one in the portal under Developers → API keys; the full key is shown once, at creation, and never again — the server keeps only a hash of it and a short prefix for the key list.
Keys and environments
A key's environment is legible in the key itself: sk_… is live, sk_test_… is sandbox. Sandbox keys create sandbox sessions whose data never mixes with live data, which makes them the right thing to build against.
curl https://api.proctor.dev/v1/api/sessions \
-H "Authorization: Bearer $PROCTOR_API_KEY"The response envelope
Every response carries the same shape, so a client can branch on success before it knows anything else about the route. Errors carry a stable machine-readable code — branch on that, never on the message, which is written for people and may be reworded.
{ "success": true, "data": { "id": "ses_…", "state": "scheduled" } }
{ "success": false, "error": { "code": "not_found", "message": "Session not found." } }Rate limits
Two fixed windows of 60 seconds: 120 requests per key and 600 across the whole organization. Every response reports where you stand, so a batch job can pace itself instead of discovering the ceiling by being refused.
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in this window. |
RateLimit-Remaining | Requests left in it. |
RateLimit-Reset | Seconds until the window resets. |
RateLimit-Scope | Which ceiling a 429 hit — key or org. |
Retry-After | On a 429: how long to wait. The SDK honours it for you. |
Idempotency
Every write accepts an Idempotency-Key. Repeating a request with the same key and the same body replays the original response verbatim, marked Idempotency-Replayed: true, instead of creating a second session. Repeating a key with a *different* body is refused — quietly serving the old result for a new request is the exact failure idempotency exists to prevent.