Uma chave da API do Fleet permite que você se comunique diretamente com sua instância do Fleet. Use uma para executar scripts, obter dados de dispositivos ou conectar o Fleet a outras ferramentas.

Funcionalidade

Visão Geral

As chaves da API do Fleet (FleetDM) autenticam solicitações enviadas diretamente para sua instância do Fleet. Você pode criá-las de três maneiras:

• Do Factorial IT, como uma chave somente leitura.
• Do painel do Fleet, como um token vinculado à sua conta de usuário do Fleet.
• Da linha de comando, com o Fleet CLI ou a API do Fleet.

Os tokens da API do Fleet nunca expiram por conta própria.

Como usar: criar uma chave do Factorial IT

1. Vá para Configurações > Desenvolvedores e role para baixo até a seção Chave da API do FleetDM.
2. Digite um Nome da chave, por exemplo, a ferramenta que usará a chave.
3. Clique em Gerar chave.
4. Copie o token mostrado na janela Chave da API do FleetDM criada. Ele permanece disponível depois na tabela de chaves.

As chaves criadas a partir do Factorial IT são somente leitura. Elas podem ver todos os dispositivos e seus dados, mas não podem alterar configurações ou executar ações em dispositivos. Elas são adequadas para integrações externas que precisam apenas ler sua instância do Fleet.

Para revogar uma, abra o menu ⋯ na sua linha na tabela Chave da API do FleetDM e clique em Revogar. Qualquer integração que a utilize para de funcionar imediatamente.

Mantenha o token em segredo. Quem o possui pode ler seu inventário de dispositivos.

Criar uma chave do painel do Fleet

1. Abra seu painel do Fleet a partir do console via Configurações > MDM > Abrir Fleet.
2. Clique no seu avatar no canto superior direito e selecione Minha conta.
3. Role para baixo até Token da API.
4. Clique em Obter token da API.
5. Copie o token. Ele pertence à sua conta de usuário do Fleet.

Este token possui as mesmas permissões que sua conta de usuário do Fleet. Mantenha-o em segredo.

Criar uma chave da linha de comando

Com o Fleet CLI:

fleetctl login --email seu-email@exemplo.com --url https://<sua-instância-do-fleet>
fleetctl get api-token

Ou diretamente através da API do Fleet:

curl -X POST https://<sua-instância-do-fleet>/api/v1/fleet/users/<user-id>/api_token \
  -H "Authorization: Bearer SEU_TOKEN_EXISTENTE" \
  -H "Content-Type: application/json"

Usar a chave

Envie o token no cabeçalho Authorization:

curl https://<sua-instância-do-fleet>/api/v1/fleet/hosts \
  -H "Authorization: Bearer SEU_TOKEN_DA_API_DO_FLEET"

Regenerar ou revogar um token

• Chave criada a partir do Factorial IT: vá para Configurações > Desenvolvedores > Chave da API do FleetDM, abra o menu ⋯ na sua linha e clique em Revogar.
• Token vinculado à sua conta de usuário do Fleet: no Fleet, vá para Minha conta e clique em Regenerar token da API. O token antigo para de funcionar imediatamente.

Solução de Problemas e FAQ

Solução de Problemas

• Uma integração parou de funcionar. Sua chave pode ter sido revogada, ou o token do usuário regenerado. Crie uma nova chave e atualize a integração.
• Uma solicitação para mudar configurações ou executar uma ação falha. Chaves criadas a partir do Factorial IT são somente leitura. Use um token vinculado a uma conta de usuário do Fleet com as permissões corretas.
• Você perdeu o token. Para uma chave criada a partir do Factorial IT, encontre-a novamente na tabela de chaves. Para um token de usuário, regenere-o em Minha conta no Fleet.

FAQ

1. Os tokens da API do Fleet expiram?
   Não. Eles permanecem válidos até que você os revogue ou regenere.
    
2. O que uma chave criada a partir do Factorial IT pode fazer?
   Ler todos os dispositivos e seus dados. Não pode alterar configurações ou executar ações em dispositivos.
    
3. Quais permissões tem um token do painel do Fleet?
   As mesmas que sua conta de usuário do Fleet.
    
4. O que acontece quando eu revogo uma chave?
   Toda integração que a utiliza para de funcionar imediatamente.