Gerenciamento de chaves da API
Formato de token, fluxo de criação, os 8 escopos de permissão, ciclo de vida, análise de uso e melhores práticas de segurança.
A API Key é sua única credencial para falar com a plataforma aberta Braidrun. Cada chave carrega um conjunto de escopos (mecanismo de permissão) e um Token. Se perdido ou vazado, a nova criação será revogada imediatamente.
Formato do item
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— Prefixo de marca para tornar identificável a ferramenta git secret-scanning / log dessensibilization<id>— Uma base de 16 caracteres62 ID público, utilizável como uma chave de pesquisa (não sensível)<secret>— 32-byte random secret, base64url coding (sensível, nenhuma mensagem de logs/erro permitida para ser enviada)
Ao gerar uma chave API, o Token original é exibido apenas uma vez na caixa de diálogo criação. Após o fechamento, o servidor apenas retém o hash Argon2id e não pode rever o texto original. Por favor, copie e salve para sua ferramenta de gerenciamento de chaves (1Password/Vault/Doppler/GitHub Secrets/etc) agora.
Criar chave de API
- Visite o console → Configurações de conta → Chave API
- Clique em "Nova chave API"
- Preencher: nome (para identificação), lista de escopo, período de validade (permanente / 30 dias / 90 dias / 1 ano)
- Clique em "Gerar chave" → Copiar Token agora
Âmbito de aplicação
Escopos são permissões de grãos finos — 8 no total: 7 você pode conceder a si mesmo, e CLUSTER ADMIN é apenas administrador. Conceda uma chave o mínimo possível; siga o menor privilégio.
| Scope | o que pode ser feito | Cenários típicos |
|---|---|---|
WEBHOOK_TRIGGER | Activar o Webhook ligado a esta Chave | GitHub Push → Workflow; upstream business system callback |
APPROVAL_RESPOND | Aprovar ou rejeitar as etapas de homologação manual — abrange a homologação Webhook e os parâmetros de homologação v1 (/api/v1/aprovações/*, incluindo a listagem das homologações pendentes, os pormenores de leitura e a apresentação de um formulário de homologação editado) | Links de aprovação de um clique em e-mail ou Slack; integração com sistemas de aprovação externos |
WORKFLOW_READ | Definições de workflow lista/leia | Mostrar a lista de workflows actual num painel externo |
WORKFLOW_EXECUTE | Iniciar workflows através da API (substituição do modo webhook) | Integração SDK; testes automatizados; tarefas em lote |
EXECUTION_READ | Perguntar o estado da execução / ler o resultado completo | Resultados da execução do Backflow para a empresa BI/data warehouse |
EXECUTION_CANCEL | Cancelar uma execução em execução | Botão "Parar" no painel de gestão/disjuntor de emergência |
ARTIFACT_READ | Listar produtos de execução / obter link de download | Arquivar os relatórios para armazenamento de objetos; enviar os resultados para sistemas a jusante |
CLUSTER_ADMIN | Apenas para administração: leia o status do cluster e gerencie políticas de autoscaling. Apenas os administradores podem conceder; quando um não- administrador cria uma Chave, este escopo é despojado automaticamente | Contas de serviço para o funcionamento de uma implantação self-hosted |
Ciclo de vida
- criar — Self-service do usuário; escopo + período de validade é decidido por você
- Utilização — Cada chamada bem sucedida acumula automaticamente o uso e atualiza o últimoUsedAt timestamp.
- Revogar — Os usuários podem clicar em "Revogar" na página "Chave API" a qualquer momento; idempotent
- Termo — expiraNo expira imediatamente após a chegada; nenhuma revogação ativa é necessária
Análise da dose
Para cada chave, clique em "Usar" na tabela "Chave API" e uma análise do gráfico aparecerá:
- Número cumulativo de chamadas + dentro da janela (7/30/90/180 dias opcional)
- Dia de pico (que dia tem mais chamadas)
- Gráfico de linhas de chamadas diárias
- Gráfico pie da distribuição do endpoint da chamada (webhook.trigger/workflow.execute/etc)
- Última vez usada
A utilização conta apenas as respostas bem sucedidas (HTTP 2xx). Falhas de autenticação/requisitos limitados por taxa não são contados.
Melhores práticas de segurança chave
- Use chaves independentes para cada ambiente (produção/estacionamento/local) - somente o ambiente afetado será revogado em caso de incidente
- Cada integração externa usa uma chave separada - use "Usagem" para ver qual integração está em uso
- Nunca enviar o Token para o repositório de código
- Injectar como Secreto encriptado no CI/ CD; não imprimir nos registos
- Observe que o tempo "recentemente utilizado" é diferente da sua expectativa → revogue imediatamente e verifique os logs
- As chaves dadas aos parceiros de curto prazo devem ser definidas para expirar em (recomendado no prazo de 90 dias)