Developer platformAdministrators
API keys and the public API
Create a least-privilege API key and safely handle pagination, limits and retries.
Last reviewed: 2026-07-21
Before you start
- A Max or Enterprise plan with External Integrations enabled
- Developer integration management permission
Steps
Create and scope the key
Copy the one-time aosk_ secret, grant only required scopes, and restrict teams or inboxes. Tenant-wide customer scope is required for customer profile writes.
Expected result: A compromised key cannot reach unrelated resources.
Use the versioned contract
Send X-AOS-Api-Key to /api/v1/external. IDs are strings, times are UTC ISO, cursor pages default to 50 and max at 100. Read rate headers, back off after 429, and use a stable Idempotency-Key for message retries. OpenAPI is at /api/v1/external/openapi.json.
Expected result: Retries do not overload the service or duplicate replies.