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

# Authentication

> API keys, environments and permissions.

Every request except `GET /v1/health` needs an API key, sent as a bearer token:

```bash theme={"system"}
curl https://api.osaconnection.com/v1/me \
  -H "Authorization: Bearer osa_live_…"
```

A missing, malformed, revoked or expired key gets `401 invalid_key`.

## Keys

| Prefix | Environment | Reaches |
| - | - | - |
| `osa_live_` | Live | Your firm's real claims and adjusters. Test claims and test accounts also appear in lists, marked `test: true`, so you can skip them. |
| `osa_test_` | Test | Only your firm's test claims and test accounts. See [Testing](/testing). |

* **One firm per key.** A key always acts for the firm it was issued to; there is no header to choose a firm. Another firm's claims return `404 not_found`.
* **One purpose per key.** Each key is issued for one integration or system. A new purpose means a new key.
* **Shown once.** OSA stores only a fingerprint of the key. Keys are delivered through a one-time, expiring link and are never sent by plain email. If a key is lost, ask [OSA](/introduction#support) for a new one.
* **Rotation.** Ask [OSA](/introduction#support) for a replacement key; both keys work while you switch over, then the old one is revoked.
* **Revocation** takes effect within about a minute.
* **Expiry.** A key does not expire unless an expiry date was agreed when it was issued.

<Warning>
  Keys belong on your servers only. Never embed one in a browser page, a mobile app, logs, or source control. If a key may have leaked, [contact OSA](/introduction#support) to revoke it.
</Warning>

## Permissions

Each operation needs a permission (scope). Your key has the permissions that your firm's plan includes and that the key was issued for. Your firm's plan can change without a new key; what a key was issued for is fixed, so a wider purpose means a new key. `GET /v1/me` shows what your key has now, as `scopes`.

| Permission | Allows |
| - | - |
| `claims:create` | `POST /v1/claims` |
| `claims:read` | `GET /v1/claims`, `GET /v1/claims/{id}` |
| `claims:write` | `POST /v1/claims/{id}/assignment` |
| `adjusters:read` | `GET /v1/adjusters` |
| `adjusters:write` | `POST /v1/adjusters/invitations`, `DELETE /v1/adjusters/invitations/{osa_id}` |

A valid key without the needed permission gets `403`: `insufficient_scope` when the key's purpose doesn't include it, or `not_in_plan` when your firm's plan doesn't.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.