API Keys no Portal Nyverra: integração máquina-a-máquina com controle

Toda operação madura acaba esbarrando no mesmo pedido: “integre o portal com o nosso sistema”. Seja um script de importação, um dashboard externo ou um conector de monitoramento, integrações precisam de credenciais próprias — não da senha de um funcionário. É para isso que existem as API Keys do Portal Nyverra ITSM.

Este guia explica o que são, como funcionam os escopos, como usá-las na API REST e por que o Portal do Desenvolvedor é o ponto de partida do integrador.

Interface do módulo no Portal Nyverra ITSM.

O que é uma API Key

É uma credencial que autentica chamadas máquina-a-máquina (M2M) à API do Portal, sem sessão de usuário. Em vez de “logar como alguém”, o sistema integrador apresenta a chave e recebe acesso conforme os escopos concedidos.

Isso traz três vantagens imediatas: segregação (a integração não é uma pessoa), controle (a chave tem escopo limitado) e rastreabilidade (as ações ficam associadas à chave).

Escopos: o que a chave pode fazer

Uma boa API Key não tem acesso total — tem o necessário. No Portal Nyverra, as operações são protegidas por escopos, por exemplo:

Escopo	Permite
posts:read / posts:write	Ler e criar/atualizar conteúdo
taxonomy:read / taxonomy:write	Ler e criar categorias/tags
media:write	Enviar arquivos/mídia
ai:generate	Usar recursos de geração de conteúdo
posts:delete / posts:purge	Excluir (com e sem recuperação)

Aplicar o menor escopo é o que reduz o estrago caso a chave vaze.

Como usar na API REST

A API aceita a chave em cabeçalho, em geral como Authorization: Bearer <chave> ou X-API-Key: <chave>. O Portal do Desenvolvedor (documentação da API) reúne os endpoints, parâmetros e exemplos — e, no caso do blog, há uma referência interativa dedicada.

Quem usa

Perfil	Uso
Desenvolvedor / integrador	Consome a API com a chave
Administrador	Cria, escopa, desativa e rotaciona chaves

Como usar: passo a passo

1. Crie uma chave por integração (nunca uma só para tudo).
2. Aplique o menor escopo necessário.
3. Guarde em cofre de segredos — jamais no código ou no Git.
4. Use a chave no cabeçalho das chamadas.
5. Monitore o uso e rotacione periodicamente.
6. Revogue a chave ao desativar a integração.

Regras de negócio e segurança

Regra	Explicação
Uma chave por sistema	Facilita revogar sem afetar outras integrações.
Escopo mínimo	Limita o impacto de um vazamento.
Rotação	Reduza a janela de exposição; troque chaves periodicamente.
Nunca versionar	Chaves no repositório são vazamento esperando para acontecer.
Auditoria	O uso da chave deve ser registrado e monitorado.

Boas práticas

• Trate a API Key como credencial sensível: cofre, não código.
• Rotacione com regularidade e revogue chaves ociosas.
• Use escopos para separar leitura de escrita e limitar exclusões.
• Prefira chaves distintas por ambiente (homologação ≠ produção).
• Documente qual integração usa qual chave.

Erros comuns

Situação	O que fazer
“A chave pode tudo”	Reescope: aplique o menor privilégio.
Chave no repositório	Revogue imediatamente e mova para o cofre.
Chave antiga esquecida	Revise e revogue chaves sem uso.
Erro API_KEY_SCOPE_DENIED	Falta escopo para a operação; ajuste a chave.

Perguntas frequentes

API Key substitui o login de usuário?
Para integrações M2M, sim; para uso humano, não.

Posso usar a mesma chave em dois sistemas?
Tecnicamente sim, mas é má prática — dificulta revogar e auditar.

Onde vejo os endpoints?
No Portal do Desenvolvedor / documentação da API REST.

Cenários de uso: integrações reais

1. Sincronização com sistema externo. Um script noturno importa dados de outro sistema usando uma chave com escopo apenas de leitura — reduzindo o que um vazamento poderia expor.

2. Conector de monitoramento. O Zabbix cria chamados via API com uma chave dedicada de escrita, separada de qualquer credencial humana.

3. Automação com agente. Ferramentas de IA ou relatórios usam ai:generate e escopos específicos, sem acesso a exclusões.

KPIs e governança de chaves

Indicador	O que revela
Chaves ativas por integração	Inventário de acessos M2M
Idade da última rotação	Postura de segurança
Chaves com escopo amplo	Risco de privilégio excessivo
Chaves sem uso recente	Candidatas a revogação

Resposta a incidente de chave exposta

Se uma chave vazar, o tempo importa. O roteiro: revogar imediatamente, criar uma nova com escopo mínimo, atualizar a integração e investigar o uso indevido pela auditoria. Use escopos separados para que a rotação de uma integração não afete as demais — e nunca versione chaves. Tratar a API Key como credencial de primeira classe é o que permite à empresa abrir a API sem abrir um flanco de segurança.

Checklist de API Keys

1. Uma chave por integração.
2. Aplique o menor escopo.
3. Guarde em cofre de segredos.
4. Rotacione periodicamente.
5. Monitore o uso.
6. Revogue chaves ociosas.

Perguntas frequentes adicionais

Onde usar a chave?
No cabeçalho Authorization ou X-API-Key das chamadas.

Posso usar a mesma chave em testes e produção?
Melhor não; separe por ambiente.

O que fazer se vazar?
Revogar imediatamente, criar nova e investigar pela auditoria.

Conclusão

Com API Keys bem geridas, o Portal Nyverra ITSM integra-se com segurança e sem depender de credenciais humanas. Escopos mínimos, rotação e auditoria transformam “abrir a API” em uma integração controlada e sustentável.