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

# Authentication

> How to authenticate requests — API keys and session tokens.

Every request carries a Bearer credential in the `Authorization` header. The API
accepts **two kinds**, on the same endpoints:

```
Authorization: Bearer ck_live_YOUR_SECRET   # API key  — integrators
Authorization: Bearer <jwt>                 # session JWT — the web app
```

The server detects which one you sent. The only difference is billing: API-key
calls draw a platform fee; JWT calls don't (see [Billing](/en/billing)).

<Note>
  If you're building an integration, use an **API key**. The session JWT is what
  clipping.cc itself uses after you log in. These guides assume an API key.
</Note>

## API keys

Create and revoke keys from the dashboard at
[clipping.cc/account](https://clipping.cc/account):

* **Create** — the full secret (`ck_live_…`) is shown **once**. The server keeps
  only a hash; there's no way to recover it later. Lose it → revoke and recreate.
* **Revoke** — immediate. Requests with a revoked key start returning `401`.
* **Multiple keys** — one per environment/integration, with descriptive names.

<Warning>
  A key carries your account's access and draws from your balance. Treat it like
  a password: never ship it in frontend code or commit it to a repository.
</Warning>

## Session tokens (JWT)

For completeness — used by the app, not usually by integrations:

* `POST /v1/auth/signup` / `POST /v1/auth/login` → returns a `token` (JWT).
* Send it as `Authorization: Bearer <jwt>`.
* `POST /v1/auth/logout-all` revokes every token; `POST /v1/auth/api-keys`
  (JWT-authenticated) is how the dashboard mints API keys.
* The realtime WebSocket (`/v1/realtime`) accepts **only** a JWT (passed as a
  query param) — API keys can't open it. Integrators poll executions instead
  (see [Asynchronous operations](/en/async-operations)).

## Errors

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| `401`  | Credential missing, invalid, or revoked.                                   |
| `402`  | Valid API key, but the account has no balance. See [Billing](/en/billing). |
| `403`  | Authenticated, but the route requires an admin role.                       |

All errors share the same shape:

```json theme={null}
{ "erro": "API key inválida — use Authorization: Bearer ck_live_…" }
```

## Access scope

A credential inherits your account's reach: you read and write your own items,
collections and reporters, plus whatever is **public** via `discover`. There are
no per-permission scopes yet — a key can do what you can do.