Authentication
How Everyn API clients authenticate, select organizations, and use scopes.
Everyn product API calls use organization-owned API keys. A machine key selects exactly one organization, so product routes derive tenant context from the bearer credential instead of trusting caller-supplied organization identifiers.
Authentication model
Use the standard bearer header for machine/API-key calls:
Authorization: Bearer sk-everyn-...Product API keys are machine principals. They can call the product surfaces covered by the scopes below, but they cannot manage organizations, members, invitations, audit events, or API keys.
Organization admin routes need a human principal, which can be presented two ways: a browser session, or a bearer credential that is not an API key. The failure modes differ — a lapsed browser session returns session_expired, while a rejected bearer credential returns authentication_failed.
Implemented machine-key scopes:
| Scope | Used for |
|---|---|
datasets:read / datasets:write | Dataset reads and dataset upload intake. |
job_specs:read / job_specs:write | Model catalog reads and job spec management. |
runs:read / runs:write | Run creation, start, cancel, retry, inspection, rows, outputs, and failures. |
exports:read / exports:write | Export creation, polling, listing, and download. |
alert_rules:read / alert_rules:write | Alert rules and alert delivery inspection. |
webhooks:read / webhooks:write | Webhook endpoints, secret rotation, tests, and delivery inspection. |
Common auth outcomes:
| Status | Meaning | Next step |
|---|---|---|
401 authentication_failed | Missing, malformed, unknown, revoked, or expired credential. | Replace the bearer credential. |
403 authorization_failed | Credential is valid but lacks the required scope or role. | Use a credential with the required scope or admin role. |
404 not_found | Resource does not exist for the authenticated organization. | Verify the ID belongs to the same organization before retrying. |
Use API errors for recovery patterns and generated reference for endpoint-level auth requirements.