> ## 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.

# Autenticação

> Como autenticar requests — API keys e tokens de sessão.

Todo request leva um crachá Bearer no header `Authorization`. A API aceita
**dois tipos**, nos mesmos endpoints:

```
Authorization: Bearer ck_live_SEU_SEGREDO   # API key  — integradores
Authorization: Bearer <jwt>                 # JWT de sessão — o app web
```

O servidor detecta qual você mandou. A única diferença é a cobrança: chamada com
API key paga taxa de plataforma; com JWT não (veja [Cobrança](/pt/billing)).

<Note>
  Se você está construindo uma integração, use uma **API key**. O JWT de sessão
  é o que o próprio clipping.cc usa depois do login. Estes guias assumem API key.
</Note>

## API keys

Crie e revogue keys no painel em
[clipping.cc/account](https://clipping.cc/account):

* **Criar** — o segredo completo (`ck_live_…`) aparece **uma vez**. O servidor
  guarda só um hash; não dá pra recuperar depois. Perdeu → revoga e cria outra.
* **Revogar** — imediato. Requests com a key revogada passam a dar `401`.
* **Várias keys** — uma por ambiente/integração, com nomes descritivos.

<Warning>
  Uma key carrega o acesso da sua conta e consome do seu saldo. Trate como senha:
  nunca exponha em código de frontend nem comite num repositório.
</Warning>

## Tokens de sessão (JWT)

Pra completar — usado pelo app, normalmente não por integrações:

* `POST /v1/auth/signup` / `POST /v1/auth/login` → retorna um `token` (JWT).
* Mande como `Authorization: Bearer <jwt>`.
* `POST /v1/auth/logout-all` revoga todos os tokens; `POST /v1/auth/api-keys`
  (autenticado por JWT) é como o painel cria as API keys.
* O WebSocket de realtime (`/v1/realtime`) aceita **só** JWT (na query) — API key
  não abre. Integradores fazem polling das executions
  (veja [Operações assíncronas](/pt/async-operations)).

## Erros

| Status | Significado                                                               |
| ------ | ------------------------------------------------------------------------- |
| `401`  | Crachá ausente, inválido ou revogado.                                     |
| `402`  | API key válida, mas a conta está sem saldo. Veja [Cobrança](/pt/billing). |
| `403`  | Autenticado, mas a rota exige role admin.                                 |

Todos os erros têm o mesmo shape:

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

## Escopo de acesso

Um crachá herda o alcance da sua conta: você lê e escreve seus próprios items,
coleções e reporters, mais o que for **público** via `discover`. Ainda não há
escopos por permissão — uma key faz o que você faz.