Getting started

Authentication

Authenticate every request with your secret key in the X-API-Key header. Keys are environment-specific and carry their environment in the prefix (ag_live_ / ag_test_). ag_test_ keys are for testing and debugging in Sandbox only — they are rejected by Production and must not be wired into a live integration.

Your key is shown once, when it is created. Treat it like a password: keep it server-side, never embed it in browser or mobile code, and never commit it to source control.

Scopes

Access is granted per resource through scopes. Each endpoint states the scope it requires — Empty Legs needs empty_leg:read. As new resources are added, your key is granted only the scopes you've been approved for; a request without the required scope returns PERMISSION_DENIED.

Key rotation

When a key is rotated, the new key works immediately and the previous key keeps working for a 7-day grace period. During grace, responses to the old key include the header X-API-Key-Deprecated: true — watch for it and migrate before the window closes.