O que você vai aprender#
- o que é uma chave e quais escopos ela pode ter;
- como criar uma, usá-la pela CLI, pelo MCP e pelo HTTP, e revogá-la;
- como os limites de taxa se aplicam.
A ideia#
No modo de rede, um agente ou um script usa uma chave de API que um usuário autenticado cria. A chave tem um segredo na forma vvk_<id>.<secret>; apenas um hash é armazenado, e o segredo é mostrado uma única vez, na criação. O seu ator na trilha de auditoria é key:<key id>.
| Escopo | Permite |
|---|---|
read | ler projetos, ver quadros, verificação (lint), ler tarefas |
edit | aplicar lotes de edição, desfazer e refazer, criar projetos |
media | importar mídia, remover mídias, iniciar a transcrição |
render | iniciar exportações |
admin | administrar usuários, chaves e a lixeira |
Os escopos são independentes: nenhum implica outro, admin inclusive. Os escopos efetivos de uma requisição são os escopos da chave interseccionados com o papel atual do seu dono, então rebaixar um usuário estreita as suas chaves na hora. Uma chave pode ser limitada a um projeto (não com admin). Regras de criação:
namede 1 a 60 caracteres, escopes, um subconjunto não vazio dos escopos de quem cria;expires_in_daysde 1 a 365, padrão 90 (1 a 30 quando a chave temadmin);- no máximo 10 criações por hora por usuário e 50 chaves não revogadas por usuário;
- apenas uma sessão autenticada pode criar uma chave: uma chave nunca pode criar uma chave.
Início rápido#
Entre para obter uma sessão, crie uma chave com ela e use a chave. O cabeçalho Origin é obrigatório em uma requisição não segura que usa o cookie de sessão; use o seu APP_URL.
APP=http://localhost:7878
curl -fsS -c jar.txt -H "Content-Type: application/json" -H "Origin: $APP" \
-d '{"email": "admin@example.com", "password": "choose-a-long-password"}' "$APP/auth/login"
curl -fsS -b jar.txt -H "Content-Type: application/json" -H "Origin: $APP" \
-d '{"name": "claude-code", "scopes": ["read", "edit", "media", "render"]}' "$APP/api/v1/keys"A segunda resposta traz o segredo. Guarde-o em um arquivo que só você possa ler e configure o cliente com o endereço do servidor:
export VUKEM_VIDEO_URL=https://video.example.com
vukem-video project:list --key-file ~/.vukem-video-keyOu defina VUKEM_VIDEO_KEY no ambiente. Não há opção --key, porque outros usuários podem ver os argumentos da linha de comando. As mesmas variáveis fazem o servidor MCP stdio (vukem-video mcp) conversar com o servidor remoto.
curl -fsS -H "Authorization: Bearer $(cat ~/.vukem-video-key)" "$APP/api/v1/projects"
curl -fsS -b jar.txt -H "Origin: $APP" "$APP/api/v1/keys"
curl -fsS -b jar.txt -X DELETE -H "Origin: $APP" "$APP/api/v1/keys/key_7k2m9x4q1b"A chave vai apenas no cabeçalho Authorization: Bearer. O GET /keys lista as suas próprias chaves (id, nome, escopos, projeto, criação, último uso, expiração, revogada) e nunca o segredo. Uma chave revogada para de funcionar na requisição seguinte.
Limites de taxa#
Uma chave é limitada a 300 requisições por minuto com um pico de 60 (VUKEM_VIDEO_RATE_LIMIT_PER_MINUTE); uma sessão de navegador a 1.800 (VUKEM_VIDEO_RATE_LIMIT_SESSION_PER_MINUTE). Iniciar uma tarefa e importar mídia ou um modelo (job_start, media_import, template:import) são limitados a 10 por minuto por ator (VUKEM_VIDEO_RATE_LIMIT_HEAVY_PER_MINUTE). Antes da autenticação, um endereço tem 600 requisições por minuto e 20 autenticações com falha por minuto, depois das quais é recusado antes de qualquer chave ou login ser conferido. Atrás de um proxy, defina TRUSTED_PROXIES, ou todos os clientes compartilham um único endereço.
A resposta a um limite é HTTP 429 com Retry-After e E_RATE_LIMITED, que pode ser repetido.
Erros comuns#
- Colocar uma chave em uma URL, em um argumento de linha de comando ou em um repositório. O prefixo
vvk_permite que verificadores de segredos encontrem vazamentos; se uma vazar, revogue-a. - Pedir um escopo que o seu próprio papel não tem: a criação é recusada.
- Uma chave que expirou: crie uma nova antes da data.