API Keys da Organização

API keys globais permitem automatizar operações da Zenifra sem usar a sessão pessoal de um usuário. Cada chave pertence a uma organização, registra quem criou, respeita RBAC e pode ser limitada por IP de origem.

Use esse recurso para CI/CD, scripts internos, jobs de operação e integrações server-side.

Criar uma API key

No console da organização:

acesse API Keys;
clique em Criar API key;
informe um nome descritivo;
escolha as permissões necessárias;
opcionalmente, defina IPs permitidos e expiração;
copie a chave exibida após a criação.

A chave completa aparece apenas uma vez. Depois disso, o console mostra somente metadados e o preview da key.

Usar em requisições HTTP

Envie a API key em um header de autenticação:

curl https://api.zenifra.com/v1/project \
  -H "Authorization: Bearer znf_sua_chave"

Também é aceito:

curl https://api.zenifra.com/v1/project \
  -H "x-api-key: znf_sua_chave"

Prefira Authorization: Bearer para manter compatibilidade com a CLI e ferramentas HTTP comuns.

Usar com a CLI

Em automações, use variável de ambiente:

export ZENIFRA_API_KEY=znf_sua_chave
zenifra projects --type http --page 1 --limit 15
zenifra deploy --project <project-id> --branch main

Para salvar localmente:

zenifra auth api-key --key znf_sua_chave

Como a API key já é vinculada a uma organização, comandos de automação não precisam de org set. Comandos pessoais, como listar organizações, continuam exigindo login de usuário.

Permissões e escopo

A API key usa o mesmo modelo de permissões da organização. Conceda apenas o necessário para a automação.

Exemplos:

deploy de um projeto específico;
leitura de logs e métricas;
criação de projeto via pipeline;
consulta de builds;
rotação controlada de recursos operacionais.

Se uma chave vazar, o impacto fica limitado às permissões concedidas e aos IPs permitidos.

IP allowlist

Ao criar a chave, informe IPs fixos que podem chamar a API. Quando a lista está preenchida, requisições vindas de outro IP são recusadas.

Use IP allowlist quando a automação roda em:

runners próprios;
servidores internos;
NAT corporativo;
jobs com egress IP conhecido.

O campo aceita IPv4 e IPv6 literal. CIDR não é aceito.

Revogação e rotação

Revogue uma chave quando:

ela não é mais usada;
o responsável saiu da equipe;
o IP de origem mudou;
há suspeita de vazamento;
as permissões ficaram amplas demais.

Para rotação segura, crie uma nova chave, atualize a automação, valide o uso e revogue a antiga.