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

# How to authenticate requests to the Overwatch REST API

> Learn how to create Overwatch API keys, pass them as bearer tokens, understand the key format, and choose the right role for your use case.

Every request to the Overwatch REST API must be authenticated. The API uses bearer tokens in the `Authorization` header. You generate these tokens as API keys from the dashboard or the API itself. Each key is scoped to your organization and carries a role that controls what the key is allowed to do.

## Key format

All Overwatch API keys follow this format:

```
ow_live_sk_<64-character hex string>
```

Example:

```
ow_live_sk_a3f8c2d1e4b5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
```

The first 16 characters (`ow_live_sk_xxxxx`) are stored as a non-secret prefix that identifies the key in list views. The full plaintext key is shown **only once** at creation time — Overwatch stores only a SHA-256 hash and cannot recover the key for you.

<Warning>
  Copy your key immediately after creation and store it somewhere secure (for example, a secrets manager or environment variable). You cannot retrieve the plaintext again.
</Warning>

## Passing your key in requests

Include your API key as a bearer token in the `Authorization` header on every request:

```
Authorization: Bearer ow_live_sk_...
```

### Example

```bash theme={null}
curl https://overwatchapp.dev/api/v1/monitors \
  -H "Authorization: Bearer $API_KEY"
```

Replace `$API_KEY` with your actual key, or export it as an environment variable before running the command.

## Creating an API key

You can create keys two ways:

**From the dashboard** — Go to **Settings → Security** and click **New API key**. Choose a name, role, and optional expiration date.

**From the API** — Send a `POST` request to `/api/v1/api-keys`. Only organization owners can create keys. See the [API Keys reference](/api-reference/api-keys) for the full request/response shape.

## Key expiration

Keys do not expire unless you set an `expiresAt` date when creating the key. Once a key expires, all requests made with it return `401 Unauthorized`. You can set an expiration at creation time; there is currently no endpoint to extend an expiration after creation.

## Roles and permissions

Every key is assigned one of three roles. The role determines which operations the key can perform.

| Role     | Permissions                                                        |
| -------- | ------------------------------------------------------------------ |
| `owner`  | Full access: read, write, manage org, create/delete API keys       |
| `admin`  | Read and write: create, update, delete monitors and alert channels |
| `viewer` | Read only: list and retrieve monitors, alerts, events, and status  |

When you create a key via the API, you can assign it any role up to and including your own. An `admin` cannot create an `owner`-level key.

<Note>
  Browser-based sessions are also accepted by all API routes when you are logged into the dashboard. For programmatic and server-side access, API keys are the recommended approach.
</Note>