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

# Authentication

> Bearer keys, scopes, rotation, and what Messages API credentials can access.

## Bearer token

Every request includes:

```http theme={null}
Authorization: Bearer osis_…
```

Store the secret as an environment variable on your server:

```bash theme={null}
COMMS_API_KEY=osis_xxxxxxxxxxxxxxxxx
```

<Warning>
  Never put Messages API keys in browser code, mobile apps, CI logs, or public git history. Treat them like production database passwords.
</Warning>

## Mint a key

<Steps>
  <Step title="Open Messages API">
    Sign in and go to [Messages API keys](https://comms.osis.co/dashboard/settings/api-keys).
  </Step>

  <Step title="Create key">
    Name the key after the service that will hold it (`Production worker`, `Staging`).
  </Step>

  <Step title="Pick scopes">
    Defaults (**send** + **read**) cover most backends. Add **webhooks** only if that process registers endpoints.
  </Step>

  <Step title="Copy once">
    The full secret is shown a single time. If you lose it, rotate.
  </Step>
</Steps>

## Scopes

| Scope            | Grants                                                  |
| ---------------- | ------------------------------------------------------- |
| `comms_send`     | `POST /api/v1/comms/messages`                           |
| `comms_read`     | List messages, conversations, contacts, delivery events |
| `comms_webhooks` | List and create webhook endpoints                       |

Missing scope response:

```json theme={null}
{ "error": "missing comms_send scope" }
```

HTTP **403**.

## What this key is for

| Yes                                            | No                                    |
| ---------------------------------------------- | ------------------------------------- |
| Send and receive on the line from your backend | Change org billing or plan            |
| Register webhooks for message events           | Manage dashboard users                |
| Power workers, queues, and CRON jobs           | Replace a signed-in dashboard session |

AI model calls from your code will use this same key style later — still **use the platform**, not **administer the platform**.

## Rotate and revoke

From the Messages API page:

* **Rotate** — issues a new secret; update env vars, then drop the old value.
* **Revoke** — immediate kill switch. Type the key name to confirm.

## Rate limits

Authenticated callers share per-org buckets. See [Errors & rate limits](/guides/errors-and-rate-limits).