API Keys

Les API keys sont des tokens d'authentification qui permettent d'accéder à Almirant depuis des outils externes, des scripts ou des intégrations programmatiques. Elles constituent le mécanisme principal pour connecter des clients MCP comme Claude Code, des automatisations CI/CD ou tout service qui doit interagir avec l'API Almirant.

À quoi servent-elles ?

Les API keys sont principalement utilisées pour :

• Connecter Claude Code -- Authentifier le serveur MCP Almirant afin que Claude Code puisse gérer des projets, des boards et des work items. Consultez le guide Authentification MCP pour plus de détails.
• Automatisations -- Scripts ou pipelines CI/CD qui créent des work items, mettent à jour des états ou enregistrent des sessions IA.
• Intégrations custom -- Vos propres applications qui interagissent avec l'API Almirant.

Générer une API key

1. Accédez à Configuration > API Keys.
2. Cliquez sur Générer une nouvelle API Key.
3. Saisissez un nom descriptif pour identifier le but de la key (par exemple : "Claude Code - Ordinateur de travail", "CI/CD Pipeline", "Bot interne").
4. Sélectionnez les permissions de la key.
5. Cliquez sur Créer.
6. Copiez immédiatement l'API key.

Copiez la key maintenant

L'API key complète ne s'affiche qu'une seule fois, au moment de sa création. Si vous fermez la boîte de dialogue sans la copier, vous ne pourrez pas la récupérer et devrez en générer une nouvelle.

Utiliser l'API key

Les API keys sont envoyées dans le header Authorization avec le schéma Bearer :

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

Configuration pour MCP (Claude Code)

Pour utiliser l'API key avec le serveur MCP Almirant dans Claude Code, ajoutez la configuration suivante au fichier .mcp.json de votre projet :

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

Pour le développement local, remplacez l'URL par http://localhost:3001/mcp?projectId=uuid-del-proyecto.

Consultez la référence complète Authentification MCP et Project Scoping pour davantage d'options de configuration.

Gérer les API keys

Voir les keys existantes

Depuis Configuration > API Keys, vous pouvez voir la liste de toutes les keys générées avec :

Champ	Description
Nom	Nom descriptif attribué lors de la création de la key
Préfixe	Premiers caractères de la key pour l'identifier (le reste est masqué)
Date de création	Date à laquelle la key a été générée
Dernière utilisation	Date de la dernière requête authentifiée avec cette key

Révoquer une API key

Si une API key est compromise ou n'est plus nécessaire :

1. Accédez à Configuration > API Keys.
2. Recherchez la key dans la liste.
3. Cliquez sur Révoquer.
4. Confirmez la révocation.

danger

Révoquer une API key est immédiat et irréversible. Tout service ou outil qui utilise cette key cessera instantanément de fonctionner. Veillez à mettre à jour les configurations des services concernés avant de la révoquer.

Bonnes pratiques de sécurité

Sécurité des API keys

Les API keys donnent accès aux données de votre organisation. Traitez-les avec le même niveau de sécurité qu'un mot de passe.

• Une key par service -- Générez une API key distincte pour chaque outil ou service. Si l'une d'elles est compromise, vous pouvez la révoquer sans affecter les autres.
• Noms descriptifs -- Utilisez des noms qui identifient clairement l'endroit où la key est utilisée : "Claude Code - PC bureau", "GitHub Actions - Deploy", "Bot Slack - Notifications".
• Ne partagez pas les keys -- Chaque membre de l'équipe qui a besoin d'un accès MCP doit générer sa propre API key.
• N'incluez pas les keys dans le code -- Ne commitez jamais d'API keys dans des dépôts de code. Utilisez des variables d'environnement ou des gestionnaires de secrets.
• Révisez régulièrement -- Révoquez les keys qui ne sont plus utilisées ou dont vous ne connaissez pas l'objectif.
• Effectuez une rotation des keys compromises -- Si vous pensez qu'une key a été divulguée, révoquez-la immédiatement et générez-en une nouvelle.

Exemple d'utilisation sécurisée avec des variables d'environnement

Au lieu d'écrire la key directement dans les fichiers de configuration :

# .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}"
      }
    }
  }
}

Pour les développeurs

Architecture d'authentification

Les API keys sont stockées sous forme de hash dans la table apiKeys du schema de base de données. Le flux d'authentification est le suivant :

1. Le client envoie l'API key dans le header Authorization: Bearer <key>.
2. Le backend recherche la key hashée dans la table apiKeys.
3. Si la key est valide, l'utilisateur et l'organisation associés sont récupérés.
4. Le contexte d'authentification ({ user, organizationId }) est injecté dans la requête.
5. Les routes protégées utilisent ce contexte pour filtrer les données par organisation.

Endpoints pertinents

Méthode	Route	Description
GET	/api/api-keys	Liste les API keys de l'organisation
POST	/api/api-keys	Génère une nouvelle API key
DELETE	/api/api-keys/:id	Révoque une API key

Permissions et scopes

Les API keys héritent des permissions de l'utilisateur qui les a créées. Le scope de la key est limité à l'organisation de l'utilisateur.