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. escolha a expiração (30, 60, 90 dias, 1 ano, data personalizada ou sem expiração; o padrão é 90 dias) e, opcionalmente, os IPs permitidos;
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.

Quando a criação é feita por outra API Key, a chave nova não pode ultrapassar as restrições da chave que chamou: se a chave chamadora expira, a nova precisa expirar na mesma data ou antes (sem expiração não é aceito); se a chave chamadora tem IPs permitidos, a nova precisa informar uma lista contida nela. Caso contrário, a API responde 403 com code: "API_KEY_RESTRICTIONS_EXCEEDED".

Editar uma API key

Na lista de chaves, use Editar para alterar o nome, a expiração e os IPs permitidos de uma chave ativa ou expirada. Definir uma nova data futura em uma chave expirada volta a liberá-la. As permissões não podem ser editadas: para mudar o escopo, crie uma nova chave e revogue a antiga.

Editar exige api_key.update na chave (ou em api_key:*); o owner já tem esse acesso. Chaves revogadas não podem ser editadas e respondem 404. Uma API Key não pode editar a si mesma (403), e a edição feita por outra API Key segue a mesma regra da criação: a expiração e os IPs permitidos não podem ultrapassar os da chave que chamou (403 API_KEY_RESTRICTIONS_EXCEEDED).

Pela API:

curl -X PATCH https://api.zenifra.com/v1/organizations/<organization-id>/api-keys/<api-key-id> \
  -H "Authorization: Bearer znf_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"expires_at": "2027-01-31T23:59:00.000Z"}'

O corpo aceita name, allowed_ips e expires_at (data futura ou null para remover a expiração).

Aviso de expiração

Quando faltam 30 dias para uma chave expirar, a Zenifra envia um e-mail para quem criou a chave e para o responsável pela organização, com o nome da chave, o preview e a data de expiração. Para manter a automação funcionando, estenda a expiração pela edição ou faça a rotação da chave.

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.

Escopo efetivo

A cada requisição, a chave vale somente a interseção entre os scopes concedidos a ela e as permissões atuais de quem a criou na organização (diretas ou herdadas de políticas). Chaves criadas pelo owner valem o escopo integral concedido a elas enquanto ele continuar owner.

• Se o criador perde uma permissão, por mudança de papel, de permissões diretas, de políticas vinculadas ou pela edição ou remoção de uma política, a chave perde o mesmo acesso na hora, sem precisar ser editada. Se ele voltar a receber a permissão, a chave volta a valer até o limite dos próprios scopes.
• Se o criador deixa de ser membro ativo da organização ou exclui a conta, a chave deixa de autenticar e as requisições recebem 401.
• Na transferência de propriedade, o antigo owner passa a ser member sem permissões, então as chaves criadas por ele deixam de ter acesso até que o novo owner conceda permissões a ele. Antes de transferir, crie as chaves das automações críticas com o novo owner ou com um membro dedicado.

Ao criar um projeto com uma API Key, a própria chave recebe project.read, project.image.update e project.deploy.trigger no projeto novo, para que o pipeline consiga publicar nele. Quem criou a chave, quando não é owner, recebe os mesmos grants.

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 Preview estiver habilitado 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.env.read",
        "project.preview.read",
        "project.preview.deploy",
        "project.preview.delete"
      ]
    }
  }
}

O Preview herda as variáveis de ambiente do projeto principal, por isso criar ou atualizar um Preview exige project.env.read ou project.image.update no projeto principal. Sem nenhum dos dois, a API responde 403 com code: "PREVIEW_ENV_ACCESS_REQUIRED".

project.preview.configure não é necessário para o ciclo operacional. As configurações de Preview aceitam API Key da organização: consultá-las exige project.preview.read e alterá-las exige project.preview.configure. Conceda project.preview.configure somente à automação que realmente precisa habilitar ou alterar Previews. 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 cinco scopes do exemplo anterior. Não adicione project.preview.configure se a automação não altera as configurações de Preview.

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 com 403 e code: "API_KEY_IP_NOT_ALLOWED".

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. Endereços IPv4 representados em IPv6 (como ::ffff:203.0.113.10) são comparados como o IPv4 correspondente.

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, ou quando ele exclui a conta, as API Keys e as chaves de IA 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