API Keys

As API keys são tokens de autenticação que permitem acessar o Almirant a partir de ferramentas externas, scripts ou integrações programáticas. Elas são o principal mecanismo para conectar clientes MCP como o Claude Code, automações de CI/CD ou qualquer serviço que precise interagir com a API do Almirant.

Para que servem

As API keys são usadas principalmente para:

• Conectar o Claude Code -- Autenticar o servidor MCP do Almirant para que o Claude Code possa gerenciar projetos, boards e work items. Consulte o guia de autenticação MCP para mais detalhes.
• Automações -- Scripts ou pipelines de CI/CD que criam work items, atualizam status ou registram sessões de IA.
• Integrações personalizadas -- Aplicações próprias que interagem com a API do Almirant.

Gerar uma API key

1. Acesse Configurações > API Keys.
2. Clique em Gerar nova API Key.
3. Informe um nome descritivo para identificar a finalidade da key (por exemplo, "Claude Code - notebook de trabalho", "Pipeline de CI/CD", "Bot interno").
4. Selecione as permissões que a key terá.
5. Clique em Criar.
6. Copie a API key imediatamente.

Copie a key agora

A API key completa é exibida apenas uma vez, no momento de criação. Se você fechar o diálogo sem copiá-la, não poderá recuperá-la e terá de gerar uma nova.

Usar a API key

As API keys são enviadas no cabeçalho Authorization com o esquema Bearer:

curl -H "Authorization: Bearer tu-api-key-aqui" \
  https://api.almirant.ai/api/projects

Configuração para MCP (Claude Code)

Para usar a API key com o servidor MCP do Almirant no Claude Code, adicione a seguinte configuração ao arquivo .mcp.json do seu projeto:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=uuid-del-proyecto",
      "headers": {
        "Authorization": "Bearer tu-api-key-aqui"
      }
    }
  }
}

Para desenvolvimento local, substitua a URL por http://localhost:3001/mcp?projectId=uuid-del-proyecto.

Consulte a referência completa de autenticação MCP e Project Scoping para mais opções de configuração.

Gerenciar API keys

Ver keys existentes

Em Configurações > API Keys, você pode ver a lista de todas as keys geradas com:

Campo	Descrição
Nome	Nome descritivo atribuído ao criar a key
Prefixo	Primeiros caracteres da key para identificá-la (o restante fica oculto)
Data de criação	Quando a key foi gerada
Último uso	Data da última requisição autenticada com essa key

Revogar uma API key

Se uma API key for comprometida ou não for mais necessária:

1. Acesse Configurações > API Keys.
2. Encontre a key na lista.
3. Clique em Revogar.
4. Confirme a revogação.

perigo

Revogar uma API key é imediato e irreversível. Qualquer serviço ou ferramenta que use essa key deixará de funcionar na hora. Atualize as configurações dos serviços afetados antes de revogá-la.

Boas práticas de segurança

Segurança das API keys

As API keys fornecem acesso aos dados da sua organização. Trate-as com o mesmo nível de segurança de uma senha.

• Uma key por serviço -- Gere uma API key diferente para cada ferramenta ou serviço. Se uma for comprometida, você poderá revogá-la sem afetar as demais.
• Nomes descritivos -- Use nomes que identifiquem claramente onde a key é usada: "Claude Code - PC do escritório", "GitHub Actions - Deploy", "Bot do Slack - Notificações".
• Não compartilhe keys -- Cada membro da equipe que precisa de acesso ao MCP deve gerar sua própria API key.
• Não inclua keys no código -- Nunca faça commit de API keys em repositórios de código. Use variáveis de ambiente ou gerenciadores de segredos.
• Revise periodicamente -- Revogue as keys que não são mais usadas ou cuja finalidade você desconhece.
• Faça a rotação de keys comprometidas -- Se suspeitar que uma key vazou, revogue-a imediatamente e gere uma nova.

Exemplo de uso seguro com variáveis de ambiente

Em vez de escrever a key diretamente nos arquivos de configuração:

# .env (excluido de git via .gitignore)
ALMIRANT_API_KEY=tu-api-key-aqui

// .mcp.json (usa referencia a variable de entorno si tu herramienta lo soporta)
{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${ALMIRANT_API_KEY}"
      }
    }
  }
}

Para desenvolvedores

Arquitetura de autenticação

As API keys são armazenadas com hash na tabela apiKeys do schema do banco de dados. O fluxo de autenticação é:

1. O cliente envia a API key no cabeçalho Authorization: Bearer <key>.
2. O backend procura a key com hash na tabela apiKeys.
3. Se a key for válida, o usuário e a organização associados serão obtidos.
4. O contexto de autenticação ({ user, organizationId }) é injetado na requisição.
5. As rotas protegidas usam esse contexto para filtrar os dados por organização.

Endpoints relevantes

Método	Rota	Descrição
GET	/api/api-keys	Lista as API keys da organização
POST	/api/api-keys	Gera uma nova API key
DELETE	/api/api-keys/:id	Revoga uma API key

Permissões e scopes

As API keys herdam as permissões do usuário que as criou. O escopo da key é limitado à organização do usuário.