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

# Authentication

> OlivIA API keys (Bearer oc_sk_) and access roles

The OlivIA API authenticates with a **personal API key** sent as a bearer token on every request:

```
Authorization: Bearer oc_sk_...
```

```bash theme={null}
curl "https://{your-prod-endpoint}/v1/protocols" \
  -H "Authorization: Bearer oc_sk_xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Getting a key

API keys are issued from the platform by an administrator in your organization (there is no self-serve key endpoint). Each key is bound to a user and an organization and **inherits that user's role**: tenancy (`org_id`) and permissions are derived from the key, so you never send an organization identifier.

<Warning>
  The key is shown **only once**, at creation. Store it in a secrets manager; OlivIA keeps only a hash and cannot recover it. If it is compromised, revoke it and issue a new one.
</Warning>

## Roles and permissions

Each endpoint requires a minimum role. The key's effective role is the owning user's role.

| Operation                                   | Allowed roles                   |
| ------------------------------------------- | ------------------------------- |
| Reads (protocols, enrollments, runs, calls) | `admin`, `coordinator`, `medic` |
| Enroll patient / create run                 | `admin`, `coordinator`          |
| Archive (delete) protocol                   | `admin`, `integrator`           |

If a key lacks the required role, the API returns `403`.

## Best practices

* Use a separate key per integration or environment so it can be revoked in isolation.
* Never embed the key in front-end clients or in repositories.
* Rotate keys periodically.