All Operark API requests authenticate with a Bearer token in the
Authorization header:
Authorization: Bearer YOUR_API_KEY
401 Unauthorized. Requests for a
resource outside your organization receive 403 ORGANIZATION_MISMATCH — never a
silent empty result.
Credential types
| Type | Header | Use |
|---|
| v1 API key | Authorization: Bearer <key> | External integrations against the /api/v1/* endpoints. |
| v2 API key | Authorization: Bearer <key> | Governance, analytics, and agent execution on the v2 surface. |
| JWT | Authorization: Bearer <jwt> | Short-lived token from /api/auth/token, used by first-party apps. |
API keys are scoped to a single organization. The organization is always
derived from the key server-side — it is never read from the URL or request
body. This is what makes cross-tenant access impossible by construction.
Creating and rotating keys
- In the dashboard, open Settings → API Keys.
- Create a key, give it a name, and copy it — the full value is shown once.
- To rotate, create a new key, deploy it, then revoke the old one.
Store keys in a secret manager or environment variables. Never embed an API
key in frontend code or a public repository.
Errors
Operark uses conventional HTTP status codes and a consistent error envelope:
{
"error": {
"code": "ORGANIZATION_MISMATCH",
"message": "Requested resource belongs to a different organization."
}
}
| Status | Meaning |
|---|
400 | Invalid request (validation failed). |
401 | Missing or invalid credential. |
403 | Authenticated, but not allowed (tier gate, org mismatch, veto). |
404 | Resource does not exist. |
429 | Rate limit exceeded — back off and retry. |
5xx | Server error — safe to retry idempotent requests. |
Rate limits
Auth and public endpoints are rate limited per organization. When you exceed a
limit you receive 429; respect the Retry-After header where present. 
