Gerando Chaves de API para a API Cato

Há páginas CMA separadas para os dois tipos de chaves de API.

Chaves de API - para uso pessoal de administradores individuais
Chaves de Serviço - para uso compartilhado entre diferentes principais de serviço

Visão geral

O Cato permite que você gere chaves de API no Cato Management Application (CMA) que são usadas para autenticar chamadas de API para o servidor de API do Cato. Insira a chave de API para um cliente de API, código, scripts, integração com Terraform, SIEM, MCP e outros para interagir de forma segura com os serviços da Cato.

Estes são os tipos de chaves de API:

Chaves API de Administrador são chaves pessoais vinculadas à sua conta de administrador, que você usa para seus próprios fluxos de trabalho de API. Você pode criar chaves de API de administrador apenas para si mesmo. Para mais informações, veja abaixo Chaves API de Administrador.
Chaves API de Serviço são chaves compartilhadas usadas por processos de sistema, automação ou integrações de terceiros. Essas chaves não estão vinculadas ao login de um administrador individual e são mais adequadas para casos de uso operacional. Para mais informações, veja abaixo Chaves de API Principal de Serviço.

A Cato fornece suporte granular para dois níveis de chamadas de API:

APIs de Consulta - Executar chamadas de API apenas de leitura para recuperar dados para sua conta

Permissões de Visualizador permitem executar apenas chamadas de consulta de API. Isso se aplica tanto se as permissões forem atribuídas por meio de um papel ou limitadas a páginas CMA específicas.
APIs de Configuração - Executar chamadas de API de escrita para fazer alterações de configuração na sua conta

Permissões de Editor permitem executar apenas chamadas de configuração ou de consulta de API. Isso se aplica tanto se as permissões forem atribuídas por meio de um papel ou limitadas a páginas CMA específicas.

Adicionando Chaves de API a um Cliente

Para autenticar solicitações na API Cato, inclua um cabeçalho HTTP chamado x-api-key no seu cliente de API. Defina o valor deste cabeçalho para sua chave de API da Cato usando o formato: x-api-key: <api-key>. Por exemplo: x-api-key: abcdef12345. Este cabeçalho autoriza sua solicitação e concede acesso aos endpoints relevantes da API Cato com base nas permissões associadas à sua chave.

Administradores de Serviço Principal

Um administrador principal de serviço é um tipo especial de administrador CMA criado especificamente para fluxos de trabalho baseados em API. Para suportar com segurança as integrações de sistema e processos de automação, crie administradores principais de serviço para sua conta. Isso permite que você gere chaves de API que são desvinculadas de credenciais de login pessoal e não podem ser usadas para acessar o CMA.

As credenciais de administrador principal de serviço são usadas exclusivamente para autenticação de API com uma chave de API de serviço correspondente. Esta configuração aumenta a segurança e reforça a separação de deveres para operações automatizadas.

Nota: Um novo Administrador CMA com o nome Serviço de Automação Principal (Editor) é criado automaticamente como parte da adição da chave de API do Serviço Principal às contas existentes.

Para criar um administrador principal de serviço:

No menu de navegação, clique em Conta > Administradores.
Clique em Novo.

O painel Criar Administrador é aberto.
Selecione Criar Novo e Criar como Principal de Serviço.
Insira as configurações Gerais para o administrador.
Selecione o Papel e quaisquer sites e usuários específicos que definirão as permissões para este administrador. Para saber mais sobre papéis, veja Gerenciando Papéis de Administrador Usando RBAC.

Essas permissões serão aplicadas à chave de API Principal de Serviço.
Clique em Aplicar. O administrador é adicionado à página Administradores, e o administrador principal de serviço é automaticamente ativado.

Gerando Resumo de IA

As páginas de Chaves de API e Chaves de API de Serviço permitem que você gere e revogue chaves de API. O Nome da chave de API é usado apenas para identificar cada chave e não é usado como parte do processo de autenticação.

Para segurança adicional, você pode restringir os IPs de origem ou o intervalo de IP (CIDR) para chaves de API e chaves de API de Serviço.

Nota: Certifique-se de copiar o valor da chave de API da janela pop-up. Uma vez que você feche a janela pop-up, não poderá acessar o valor da chave novamente.

Chaves de API do Administrador

Quando você precisar suportar seus próprios fluxos de trabalho de automação como um administrador individual, crie uma chave de API de administrador vinculada às suas credenciais de administrador CMA. Você só poderá criar chaves de API de administrador para seu próprio uso, não para outros administradores, e apenas através do CMA.

Quando um administrador é excluído, a chave de API associada é automaticamente desativada. Se um administrador for desativado, a chave será marcada como Desativada, e chamadas de API usando-a retornarão um erro.

Permissões RBAC para Chaves de API de Administrador

Cada chave de API de administrador herda as permissões RBAC e papéis do administrador que a criou. As permissões são atualizadas dinamicamente se os papéis RBAC do administrador mudarem, incluindo permissões para sites específicos, grupos de usuários, entre outros.
Administradores com o papel de Visualizador podem ver todas as informações de chave de API (não o valor real da chave)
Administradores com um papel RBAC de Editor que inclui a página de Chaves de API podem ver as chaves de API na conta e também revogá-las (excluí-las)

Para gerar uma chave de API de administrador:

No menu de navegação, clique em Recursos > Chaves de API de Administrador.
Clique em Novo. O painel Criar Chave de API abre-se.
Insira um Nome da Chave.
Para aplicar permissões de visualização apenas para esta chave, selecione Rebaixar para Visualizar.
(Opcional) Para maior segurança, em Permitir acesso de IPs, selecione Lista específica de IP, e defina os endereços IP ou o intervalo de IP que estão autorizados a usar esta chave de API.

A configuração padrão é permitir esta chave de API para Qualquer endereço IP.
(Opcional) Selecione uma data que a chave de API Expira em.

Para chaves de API com permissões de Editar, recomendamos definir uma data que a chave de API irá Expirar em.
Clique em Aplicar. A chave de API é adicionada à página, e uma janela pop-up contendo o valor da nova chave de API é exibida.
Clique no botão para copiar a Chave de API que é gerada pelo CMA e salvá-la em um local seguro.

Uma vez que você fechar esta janela, não poderá acessar o valor da chave de API.
Clique em OK para fechar a janela pop-up.

Chaves de API de Serviço Principal

Quando você precisar suportar fluxos de trabalho de integração ou operacionais compartilhados, crie uma chave de API de serviço na página de Chaves de API de Serviço. Essas chaves são projetadas para uso por serviços de automação e scripts que não requerem acesso ao CMA. Elas estão conectadas ao administrador principal do serviço que criou a chave.

Chaves de API de Serviço podem ser usadas em sistemas e equipes, permitindo integração escalável com ferramentas e serviços externos. Esses tipos de chaves não estão vinculados a um administrador CMA e são destinadas para operações de backend ou pipelines de entrega contínua.

Permissões RBAC para Chaves de API de Serviço

Apenas administradores com o papel de Editor podem criar ou gerenciar chaves de API principal de serviço
Cada chave de API de serviço herda as permissões RBAC e papéis do administrador principal de serviço associado à chave. Se as permissões RBAC do administrador mudarem, a chave de API principal de serviço é atualizada automaticamente com as novas permissões.

Para gerar uma chave de serviço de API:

No menu de navegação, clique em Recursos > Chaves de API de Serviço.
Clique em Novo. O painel Criar Chave API abre.
Selecione o Serviço Principal que está associado a esta chave.
Digite um Nome da Chave.
Para aplicar permissões de visualização apenas para esta chave, selecione Rebaixar para Visualizar.
(Opcional) Para segurança adicional, em Permitir acesso de IPs, selecione Lista de IPs específicos, e defina os endereços IP ou intervalo de IP que são permitidos para usar esta chave de API.

A configuração padrão é permitir esta chave de API para Qualquer IP.
(Opcional) Selecione uma data em que a chave de API Expira em.

Para chaves de API com permissões de Editar, recomendamos definir uma data em que a chave de API irá Expirar em.
Clique em Aplicar. A chave de API é adicionada à página, e uma janela pop-up contendo o valor para a nova chave de API é exibida.
Clique no botão para copiar a Chave de API gerada pela CMA e salve-a em um local seguro.

Uma vez que você fechar esta janela, não poderá acessar o valor da chave de API.
Clique em OK para fechar a janela pop-up.

Revogando uma Chave API

Você pode revogar a chave de API e removê-la do CMA. Uma vez revogada, a chave não poderá ser usada para autenticar no servidor de API.

Para revogar uma chave de API:

No menu de navegação, clique em Recursos > Chaves de API de Administrador ou Chaves de API de Serviço.
Na linha com a chave de API, clique no ícone de exclusão no final da linha.
Na janela de confirmação, clique em Excluir. A chave de API é revogada e removida da sua conta.