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

# Authentication

> Authenticate to the Opsmatic API with bearer keys, and understand key roles and permissions

## Overview

Every request to the Opsmatic API is authenticated with an API key sent as a bearer token. Keys are scoped by **role** (a preset bundle of permissions) and, optionally, to a single **organization** or a single **connection**.

```bash theme={null}
curl -H "Authorization: Bearer ops_your_api_key" \
     https://api.opsmatic.com/v1/connections
```

Requests without a valid `Authorization: Bearer …` header are rejected with `401 Unauthorized`.

## API Key Format

Opsmatic keys always start with the `ops_` prefix:

```
ops_1a2b3c4d5e6f...
```

<Warning>
  The full key is shown **only once**, at creation time. Store it in a secret manager or environment variable — Opsmatic keeps only a hash and can never display the secret again. If a key is lost or leaked, revoke it and generate a new one.
</Warning>

## Creating a Key

<Steps>
  <Step title="Open API Keys">
    In the dashboard, go to **Settings → API Keys** (or the **API Access** area).
  </Step>

  <Step title="Choose a role">
    Pick the role that grants the least access your integration needs (see the table below).
  </Step>

  <Step title="Scope it (optional)">
    Optionally bind the key to a specific organization so it only ever sees that organization's data.
  </Step>

  <Step title="Copy and store">
    Copy the `ops_…` value immediately and store it securely.
  </Step>
</Steps>

## Key Roles

Each role maps to a fixed set of permissions:

| Role               | Intended use                       | Highlights                                                                                                       |
| ------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `full-access`      | Trusted backend integrations       | Read/write/delete on connections and workflows; read analytics, usage & costs; manage organizations; send alerts |
| `read-only`        | Dashboards, reporting, exports     | Read access to connections, workflows, analytics, usage, costs and alerts — no writes                            |
| `connections-only` | Provisioning tools                 | Read/write/delete on connections only                                                                            |
| `usage-ingestion`  | OpenClaw daemons & usage reporters | Write usage/cost data for a single connection                                                                    |

<Note>
  `usage-ingestion` keys are generated automatically when you create an OpenClaw connection and are bound to that connection. You normally don't create them by hand — see the [OpenClaw setup guide](/connections/openclaw-setup).
</Note>

## Permission Model

Permissions are expressed as `resource: action` pairs. The API checks the required permission for each endpoint against your key's role.

| Resource        | Actions                   | Used by                                                                                |
| --------------- | ------------------------- | -------------------------------------------------------------------------------------- |
| `connections`   | `read`, `write`, `delete` | [Connections API](/api-reference/connections)                                          |
| `analytics`     | `read`                    | [Analytics, executions, availability, incidents & anomalies](/api-reference/analytics) |
| `usage`         | `read`, `write`           | [Usage & Cost API](/api-reference/usage)                                               |
| `costs`         | `read`, `write`           | OpenClaw cost data                                                                     |
| `workflows`     | `read`, `write`, `delete` | Workflow metadata                                                                      |
| `organizations` | `read`, `write`           | Organization scoping (see [Organizations](/api-reference/organizations))               |
| `alerts`        | `read`, `write`           | [Alerts API](/api-reference/introduction)                                              |

If a key lacks the permission an endpoint requires, the request returns `403 Forbidden`.

## Personal vs. Organization Keys

* **Personal keys** can access your own connections **and** connections belonging to any organization you're a member of.
* **Organization keys** are scoped to a single organization and only ever see that organization's data.

This scoping is applied automatically on every request — you don't pass an organization ID to "switch" context; the key determines what's visible. See [Organizations](/api-reference/organizations) for details.

## Errors

| Status | Meaning                                                                                       |
| ------ | --------------------------------------------------------------------------------------------- |
| `401`  | Missing or malformed `Authorization` header, or invalid/expired key                           |
| `403`  | Valid key, but its role lacks the required permission (or access to the requested connection) |

```json theme={null}
{
  "error": "Invalid authorization format. Use Bearer token."
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Connections API" icon="plug" href="/api-reference/connections">
    List, create, update and delete connections
  </Card>

  <Card title="Analytics API" icon="chart-line" href="/api-reference/analytics">
    Query executions, availability, incidents and aggregated metrics
  </Card>
</CardGroup>