Ir para o conteúdo

Como Gerar e Gerenciar Chaves de API com Segurança

🤖 Explicar com IA

As chaves de API são as credenciais digitais que permitem que seu software personalizado ou aplicativos de terceiros se comuniquem com segurança com o ecossistema 4Geeks. Esteja você automatizando pagamentos via 4Geeks Payments, sincronizando dados de candidatos do 4Geeks Talent ou integrando registros médicos com o 4Geeks Health, uma chave de API segura é o seu ponto de partida.

Este guia fornece um passo a passo abrangente sobre como gerar, gerenciar e proteger suas chaves de API usando o 4Geeks Console. Seguindo estas etapas, você garante que suas integrações permaneçam robustas enquanto mantém os dados da sua organização seguros.

Pré-requisitos

Antes de começar a gerar chaves, certifique-se de atender aos seguintes requisitos:

  • Acesso à Conta: Você deve ter uma conta ativa no 4Geeks Console.
  • Permissões de Usuário: Você precisa de direitos de acesso de “Admin” ou “Desenvolvedor”. Usuários comuns normalmente não têm permissão para visualizar ou criar chaves de API.
  • Configuração de Segurança: É altamente recomendável que você tenha a Autenticação de Dois Fatores (2FA) habilitada em sua conta antes de realizar ações de alta segurança, como a geração de chaves.

Instruções Passo a Passo

Siga estas etapas para criar uma nova chave de API.

Passo 1: Acessar as Configurações do Desenvolvedor

  1. Faça login no seu 4Geeks Console.
  2. Na barra lateral de navegação principal, localize e clique em Settings.
  3. No menu de configurações ou suspenso, selecione API & Developers.

Passo 2: Gerar uma Nova Chave

  1. Na seção API Keys, você verá uma lista de chaves existentes (se houver). Clique no botão + Generate New Key.
  2. Nomeie sua Chave: Digite um nome descritivo no campo “Label”.
    • Dica: Use uma convenção de nomenclatura que identifique o propósito da chave e o serviço que a utiliza (ex: Zapier-Integration-Payroll ou Internal-App-Health).
  3. Definir Expiração (Opcional): Para maior segurança, você pode definir uma data de expiração. Se esta chave for para um projeto temporário, selecione uma data; caso contrário, deixe como “Never Expire”.

Passo 3: Definir Permissões (Scopes)

Para aderir ao princípio do privilégio mínimo, conceda apenas as permissões necessárias para a tarefa específica.

  1. Revise a lista de produtos disponíveis (ex: 4Geeks Asset, 4Geeks Perks).
  2. Ative as permissões específicas de Read (Leitura) ou Write (Escrita) necessárias.
    • Exemplo: Se a chave for para um visualizador de painel, conceda acesso Read-Only ao 4Geeks Asset. Não conceda acesso Write ao 4Geeks Payroll, a menos que a integração exija explicitamente a modificação de dados salariais.
  3. Clique em Create Key.

Passo 4: Copiar e Armazenar sua Chave

Etapa Crucial: Assim que a chave for gerada, um modal exibirá a Chave Secreta da API (API Secret Key) completa.

  1. Clique no ícone Copy para copiar a string para sua área de transferência.
  2. Cole esta chave imediatamente em um cofre seguro, gerenciador de senhas ou arquivo de variável de ambiente (.env).
  3. Nota: Por motivos de segurança, a 4Geeks nunca mostrará essa chave completa novamente. Se você a perder, terá que gerar uma nova e atualizar suas integrações.

Casos de Uso Comuns

Entender como aplicar essas chaves pode ajudar a agilizar suas operações em todo o conjunto 4Geeks.

Cenário 1: Automatizando Fluxos de Trabalho de Integração (Onboarding)

Situação: Sua equipe de RH usa um portal interno personalizado e deseja acionar tarefas de integração automaticamente quando uma nova contratação é aprovada. Aplicação: Você gera uma chave de API com acesso “Write” ao 4Geeks Talent. Quando um candidato é marcado como “Contratado” em seu sistema interno, a chave de API autentica uma solicitação ao 4Geeks Talent para iniciar a sequência de onboarding.

Cenário 2: Sincronizando Inventário para E-Commerce

Situação: Você utiliza o 4Geeks Asset para rastreamento de inventário, mas usa uma ferramenta de terceiros para vendas front-end. Aplicação: Ao criar uma chave de API “Read-Only” para sua plataforma de vendas, ela pode consultar o 4Geeks Asset a cada 15 minutos para buscar níveis de estoque em tempo real, garantindo que você nunca venda um produto além do estoque.

Solução de Problemas

Se suas integrações estiverem falhando, verifique estes problemas comuns associados às chaves de API.

Problema 1: Erro HTTP 401 Unauthorized

  • Causa: A chave de API está ausente, incorreta ou foi excluída.
  • Solução: Verifique o código da sua aplicação para garantir que a chave esteja sendo passada corretamente no cabeçalho (Header) (geralmente Authorization: Bearer SUA_CHAVE_API). Se o código estiver correto, verifique no 4Geeks Console se o status da chave é “Active”.

Problema 2: Erro HTTP 403 Forbidden

  • Causa: A chave funciona, mas não tem permissão para acessar o recurso específico.
  • Solução: Você provavelmente restringiu o Escopo (Scope) durante o Passo 3. Por exemplo, se estiver tentando usar endpoints dos 4Geeks AI Agents, mas habilitou apenas permissões para o 4Geeks Perks, a solicitação falhará. Gere uma nova chave com os escopos corretos.

Problema 3: Chave Comprometida

  • Causa: Um desenvolvedor acidentalmente enviou a chave de API para um repositório público no GitHub.
  • Solução: Trate isso como uma emergência de segurança. Faça login imediatamente no console, encontre a chave comprometida e clique em Revoke/Delete. Gere uma nova chave e atualize suas variáveis de ambiente.

Melhores Práticas para Segurança

  • Gire as Chaves: Altere suas chaves de API periodicamente (ex: a cada 90 dias) para reduzir o risco de credenciais comprometidas.
  • Use Variáveis de Ambiente: Nunca codifique chaves de API diretamente no código-fonte da sua aplicação.
  • Limite os Escopos: Nunca gere uma chave de “Super Administrador” com acesso a tudo, a menos que seja absolutamente necessário. Se uma chave for necessária apenas para o 4Geeks Payroll, não dê a ela acesso aos dados do 4Geeks Health.

Conclusão

Gerenciar chaves de API com segurança é a base de uma infraestrutura técnica estável e segura. Ao configurar corretamente as permissões e tratar suas credenciais com cuidado, você pode desbloquear todo o potencial de automação dentro do ecossistema 4Geeks.

Pronto para construir sua primeira integração? Visite o 4Geeks Console para começar.

Recursos Adicionais