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:

1. acesse Chaves de API no menu lateral;
2. clique em Criar chave de API;
3. informe um nome descritivo;
4. escolha as permissões necessárias, partindo de um modelo de política, de políticas reutilizáveis ou de ajustes manuais;
5. opcionalmente, defina IPs permitidos e expiração;
6. copie a chave exibida após a criação.

Vídeo: preenchendo uma chave de API da organização e uma chave de IA.

A chave completa aparece apenas uma vez. Depois disso, o console mostra somente metadados, como status, quem criou, último acesso, último IP e expiração, além de um preview parcial da chave.

Você só pode conceder a uma API Key permissões que você já possui na organização. Criar chaves exige api_key.create em organization:*; o owner já tem esse acesso.

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.

Catálogo completo de scopes

O campo permissions.resources aceita os scopes abaixo. Use * somente quando a automação realmente precisar de todos os recursos daquele tipo; para menor privilégio, informe o ID da organização, projeto, banco, serviço ou chave correspondente.

Projetos e Previews

Templates

Bancos de dados

Serviços gerenciados

IA

API Keys da organização

Billing

Administração da organização

Administração de membros, convites e políticas, além de ações pessoais como listar organizações, aceitar convites e alterar dados da conta, exigem uma sessão de usuário.

Chave mínima para operar um Preview

Depois que um usuário autorizado habilitar Preview no projeto principal, uma automação que só precisa criar/atualizar, consultar e remover o Preview deve receber apenas estes grants no projeto principal:

{
  "resources": {
    "project": {
      "<project-id>": [
        "project.read",
        "project.preview.read",
        "project.preview.deploy",
        "project.preview.delete"
      ]
    }
  }
}

project.preview.configure não é necessário para o ciclo operacional e não deve ser concedido à automação quando a configuração inicial for feita por usuário. Para consultar custos dos Previews, adicione project.billing.read separadamente.

Requisito mínimo por operação

Cada scope abaixo é limitado ao mesmo project-id do projeto principal:

Assim, a automação que executa o ciclo completo precisa exatamente dos quatro scopes do exemplo anterior. Não adicione project.preview.configure: a configuração inicial continua sendo uma operação de usuário autorizado.

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 (ao remover um membro da organização, as API Keys criadas por ele são revogadas automaticamente);
• 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.

Próximos passos

• Permissões granulares em organizações
• CLI de deploy e automação
• Segurança na Zenifra