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

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:

{"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:

{"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

Versão em Markdown desta página