# Autenticação e escopos

## Tokens de acesso pessoal

Crie tokens no app KolWrite (**Configurações → Conta → Acesso à API**).
Os tokens têm a forma `kol_...`, são mostrados uma única vez na criação e agem como **você**:
veem seus arquivos, gastam seus créditos e respeitam os limites do seu plano.

Envie o token de uma das duas formas; as duas são equivalentes:

```
Authorization: Bearer kol_...
X-API-Key: kol_...
```

- **Validade**: por padrão os tokens não expiram; na criação você pode definir 7/30/90 dias ou uma
  data própria.
- **Revogação**: revogue qualquer token no app (ou com `DELETE
  /api/v1/api-keys/{id}` a partir de uma sessão iniciada). Vale imediatamente.
- Tokens nunca podem gerenciar tokens, excluir sua conta nem acessar endpoints
  administrativos, sejam quais forem os escopos.

## Escopos

Um token só chama endpoints cobertos pelos escopos concedidos. Cada
operação da [referência](/) indica o escopo exigido
(`x-required-scope` na [especificação OpenAPI](/openapi.json)).

| Escopo | Permite |
|---|---|
| `files:read` | Listar e baixar arquivos, pastas, mídias e uploads; ler o uso de armazenamento |
| `files:write` | Enviar arquivos, registrar mídias, criar/atualizar pastas e espaços de trabalho |
| `jobs:read` | Ler o status das tarefas, a posição na fila, os resultados e os artefatos |
| `jobs:write` | Criar e cancelar tarefas (transcrição, gravação de legendas); reordenar a fila |
| `transcripts:read` | Ler transcrições, versões e URLs de download das exportações |
| `transcripts:write` | Salvar novas versões de transcrição e restaurar as anteriores |
| `ai:use` | Usar a IA gerenciada do KolWrite (chat, embeddings, transcrição rápida); gasta créditos |
| `copilot:write` | Executar IA medida e salvar interações no Copilot geral ou no Copilot de uma transcrição autorizada |
| `shares:read` | Listar e consultar links públicos de compartilhamento |
| `shares:write` | Criar, atualizar, rotacionar e revogar links públicos de compartilhamento |
| `devices:read` | Listar sessões de dispositivos conectados |
| `devices:write` | Encerrar sessões de dispositivos |
| `account:read` | Ler flags de recursos e preferências de experiência do app |
| `account:write` | Atualizar preferências de experiência do app |
| `billing:read` | Ler saldo de créditos, extrato e concessões |

Predefinições no app: **Somente leitura** (todos os `*:read`), **Automação**
(`files:*`, `jobs:*`, `transcripts:read`, `billing:read`), **Acesso total**.

## Erros de escopo

Escopo ausente em um endpoint coberto:

```json
{"detail": {"code": "insufficient_scope",
            "message": "This endpoint requires the 'jobs:write' scope",
            "required_scope": "jobs:write"}}
```

Endpoint fora da superfície pública de tokens:

```json
{"detail": {"code": "pat_route_not_allowed",
            "message": "This endpoint is not available to personal access tokens"}}
```

Os dois retornam HTTP 403. Tokens inválidos ou revogados retornam HTTP 401 com
`invalid_api_key`.

## Créditos e cobrança

As tarefas reservam créditos ao serem criadas e acertam o valor na conclusão; as chamadas de IA são medidas
por uso de tokens. Acompanhe o gasto com `billing:read`:

- `GET /api/v1/billing/balance`
- `GET /api/v1/billing/ledger`