Get started
Authentication and API keys
Store project credentials safely, send bearer authentication, and understand credential boundaries.
Send a bearer token
Every authenticated customer API request sends the project credential in the HTTP Authorization header. The Realtime readiness endpoint is public so applications can inspect availability before exposing a voice action. Put the current preview origin and credential in a protected server environment, then construct URLs from the origin rather than repeating it throughout the application.
export OX_API_BASE_URL=https://www.amerint.co
export OX_API_KEY='[YOUR_OX_API_KEY]'
Authorization: Bearer [YOUR_OX_API_KEY]
Accept: application/json
Never put a permanent credential in browser code, a public environment variable, a mobile binary, a URL, source control, analytics, or logs. Browser voice applications mint a short-lived Realtime descriptor on their own authenticated server and return only that descriptor to the client.
Understand credential boundaries
Ox uses separate credentials for customer inference, project-scoped administration, and operator control-plane work.
| Credential | Intended use | Allowed location |
|---|---|---|
| Project API key | Enabled inference and Realtime operations for one project | Trusted server only |
| Project management key | Project resources allowed by project:read, project:write, or project:keys | Trusted server only |
| Control-plane token | Cross-project provisioning and operator workflows | Isolated operator service only |
| Realtime session secret | One short-lived browser connection | Returned to one authenticated client, never persisted |
A managed project key cannot access another project or grant scopes it does not possess. A Realtime-only key cannot use project-management routes. Raw keys and webhook signing secrets are returned only at creation time; store them immediately in a server-side secret manager.
Diagnose authentication failures
An HTTP 401 means the bearer credential is absent, malformed, expired, revoked, or unknown. An HTTP 403 means the credential is valid but lacks the required project scope. Do not retry either response automatically. Rotate a compromised key by issuing its replacement, updating the server secret, verifying traffic with the new key, and then revoking the old key.