API Clés

Les clés API sont utilisées pour authentifier les demandes adressées au Capgo API. Chaque clé peut avoir différentes autorisations (modes) pour contrôler les niveaux d’accès. Les clés sont spécifiques à l’organisation et doivent être gérées avec soin car elles accordent l’accès à vos ressources Capgo.

Modes clés

lire : ne peut lire que les données, aucune modification n’est autorisée
télécharger : peut lire, modifier et télécharger de nouveaux bundles
écrire : peut lire, modifier des données et télécharger des bundles
tout : accès complet à toutes les opérations

Les modes clés suivent un schéma par étapes/graduel. Si vous disposez d’une clé de téléchargement et que vous créez ensuite une clé d’écriture, la clé d’écriture pourra faire tout ce que la clé de téléchargement pourrait faire. Veuillez jeter un œil au schéma suivant pour mieux comprendre le fonctionnement des touches API.

Un schéma expliquant le fonctionnement de la clé API

Sous-clés avec des droits limités

Vous pouvez créer des sous-clés avec un accès limité à des applications ou des organisations spécifiques. Ceci est utile pour restreindre l’accès à certaines ressources tout en autorisant les opérations sur d’autres. Utilisez les paramètres limited_to_apps et limited_to_orgs lors de la création d’une clé pour définir ces restrictions.

Clés cryptées

Vous pouvez créer des clés API chiffrées (hachées) pour une sécurité renforcée. Lors de la création d’une clé chiffrée :

La clé est hachée en utilisant SHA-256 avant d’être stockée dans la base de données
La clé simple n’est renvoyée qu’une seule fois dans la réponse de création - enregistrez-la immédiatement
La clé ne peut pas être récupérée ou visualisée à nouveau après sa création
Si vous perdez une clé cryptée, vous devez en créer une nouvelle

Utilisez le paramètre hashed: true lors de la création d’une clé pour activer le chiffrement. Il s’agit de l’approche recommandée pour les environnements de production.

Expiration de la clé

Les clés API peuvent avoir une date d’expiration pour limiter la fenêtre d’exposition si une clé est compromise. Lorsqu’une date d’expiration est fixée :

La clé cesse de fonctionner après la date et l’heure spécifiées
Les demandes utilisant des clés expirées seront rejetées avec une erreur
Les clés expirées sont automatiquement nettoyées après 30 jours

Les organisations peuvent appliquer des politiques d’expiration :

Exiger une expiration : toutes les clés API doivent avoir une date d’expiration
Période d’expiration maximale : limite la date à laquelle une date d’expiration peut être définie dans le futur.

Bonnes pratiques de sécurité

Principe du moindre privilège : utilisez toujours le mode le plus restrictif qui permet toujours à votre intégration de fonctionner
Utiliser des clés chiffrées : créez des clés hachées pour la production afin de vous protéger contre les violations de bases de données
Définir les dates d’expiration : utilisez les dates d’expiration pour limiter la durée de vie de vos clés
Rotation régulière : faites pivoter périodiquement vos clés API
Stockage sécurisé : stockez les clés API en toute sécurité et ne les confiez jamais au contrôle de version.
Surveillance : surveillez l’utilisation des clés API et révoquez immédiatement toutes les clés compromises.
Sous-clés limitées : utilisez des sous-clés avec des droits limités pour des intégrations spécifiques afin de minimiser les risques

Points de terminaison

OBTENIR

https://api.capgo.app/apikey/

Récupérez toutes les clés API associées à votre compte.

Type de réponse

interface ApiKey {
  created_at: string | null
  id: number
  key: string | null  // null for encrypted keys
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  expires_at?: string | null  // ISO 8601 date, null means never expires
}
```> **Remarque** : Pour les clés chiffrées, le champ `key` sera `null` dans les réponses GET puisque la clé brute n'est affichée qu'une seule fois lors de la création.

#### Exemple de demande

```bash
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/

Exemple de réponse

{
  "data": [
    {
      "id": 1,
      "key": "ak_123...",
      "mode": "read",
      "name": "CI/CD Read Key",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "user_id": "user_123"
    },
    {
      "id": 2,
      "key": "ak_456...",
      "mode": "upload",
      "name": "Deploy Bot",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "user_id": "user_123",
      "limited_to_apps": ["com.demo.app"]
    }
  ]
}

POSTER

https://api.capgo.app/apikey/

Créez une nouvelle clé API pour une organisation spécifique.

Corps de la demande

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  hashed?: boolean       // Create an encrypted key (recommended for production)
  expires_at?: string    // ISO 8601 date for key expiration
}

Exemple de demande (clé standard)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Read Key",
    "mode": "read",
    "limited_to_apps": ["com.demo.app"]
  }' \
  https://api.capgo.app/apikey/

Exemple de demande (clé cryptée avec expiration)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure CI Key",
    "mode": "upload",
    "hashed": true,
    "expires_at": "2025-06-01T00:00:00Z"
  }' \
  https://api.capgo.app/apikey/

Exemple de réponse (clé standard)

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "Limited Read Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "limited_to_apps": ["com.demo.app"]
  }
}

Exemple de réponse (clé chiffrée)

{
  "apikey": {
    "id": 4,
    "key": "ak_abc123...",
    "mode": "upload",
    "name": "Secure CI Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "expires_at": "2025-06-01T00:00:00Z"
  }
}

Important : Pour les clés chiffrées, la valeur key dans cette réponse est la seule fois où vous verrez la clé brute. Enregistrez-le immédiatement dans un emplacement sécurisé. Les requêtes GET suivantes renverront null pour le champ key.

SUPPRIMER

https://api.capgo.app/apikey/:id/

Supprimez une clé API existante. Utilisez-le pour révoquer l’accès immédiatement.

Paramètres

id : L’ID de la clé API à supprimer (identifiant numérique, pas la chaîne de clé elle-même)

Exemple de demande

curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/

Réponse réussie

{
  "success": true
}

Cas d’utilisation courants

Intégration CI/CD : créez des clés en lecture seule pour les pipelines CI afin de vérifier l’état du déploiement
Automatisation du déploiement : utilisez les clés du mode de téléchargement pour les scripts de déploiement automatisés
Outils de surveillance : utilisez les touches de mode lecture pour les intégrations de surveillance externe
Accès administrateur : utilisez toutes les touches de mode avec parcimonie pour les outils d’administration
Accès limité : créez des sous-clés avec des droits limités sur des applications ou des organisations spécifiques pour les intégrations tierces

Gestion des erreurs

Scénarios d’erreur courants et leurs réponses :

// Invalid mode
{
  "error": "Invalid mode specified. Must be one of: read, write, upload, all",
  "status": "KO"
}

// Key not found
{
  "error": "API key not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage API keys",
  "status": "KO"
}

// Expired API key used for authentication
{
  "error": "API key has expired",
  "status": "KO"
}

// Invalid expiration date (in the past)
{
  "error": "Expiration date must be in the future",
  "status": "KO"
}

// Organization requires expiration
{
  "error": "Organization policy requires an expiration date for API keys",
  "status": "KO"
}

// Expiration exceeds organization limit
{
  "error": "Expiration date exceeds organization maximum of 90 days",
  "status": "KO"
}