Ir para o conteúdo

Hospedagem própria

Chaves de API e escopos

Crie, use e revogue as chaves de API que permitem a agentes e scripts usar um servidor em modo de rede.

Última atualização:

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

EscopoPermite
readler projetos, ver quadros, verificação (lint), ler tarefas
editaplicar lotes de edição, desfazer e refazer, criar projetos
mediaimportar mídia, remover mídias, iniciar a transcrição
renderiniciar exportações
adminadministrar 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:

  • name de 1 a 60 caracteres, e scopes, um subconjunto não vazio dos escopos de quem cria;
  • expires_in_days de 1 a 365, padrão 90 (1 a 30 quando a chave tem admin);
  • 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.

Terminal
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:

Terminal
export VUKEM_VIDEO_URL=https://video.example.com
vukem-video project:list --key-file ~/.vukem-video-key

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

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.

Próximos passos#