> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How Operark API requests are authenticated and authorized.

All Operark API requests authenticate with a **Bearer token** in the
`Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

Requests without a valid credential receive `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. |

<Note>
  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.
</Note>

## Creating and rotating keys

1. In the dashboard, open **Settings → API Keys**.
2. Create a key, give it a name, and copy it — the full value is shown once.
3. To rotate, create a new key, deploy it, then revoke the old one.

<Warning>
  Store keys in a secret manager or environment variables. Never embed an API
  key in frontend code or a public repository.
</Warning>

## Errors

Operark uses conventional HTTP status codes and a consistent error envelope:

```json theme={null}
{
  "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.