Authentification

Toutes les requêtes à l'API publique nécessitent une clé API.

Header

x-api-key: gfac_votre_cle_api

Alternativement, la clé peut être passée en query parameter :

GET /api/v1/automations?apiKey=gfac_votre_cle_api

Format de la clé

Les clés API Gurren commencent par le préfixe gfac_ suivi de 48 caractères hexadécimaux :

gfac_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6

Créer une clé API

Via le dashboard

1. Connectez-vous au dashboard Gurren
2. Allez dans Settings > API Keys
3. Cliquez Créer une clé
4. Choisissez un nom et les scopes
5. Copiez la clé affichée (elle ne sera plus visible)

Via l'API (JWT requis)

curl -X POST https://api.gurren.leandre.io/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "scopes": ["automation:read", "automation:execute", "pipeline:read", "pipeline:execute"]
  }'

Réponse :

{
  "apiKey": {
    "_id": "665a...",
    "name": "Production",
    "prefix": "gfac_a1b2c3",
    "scopes": ["automation:read", "automation:execute", "pipeline:read", "pipeline:execute"],
    "isActive": true,
    "createdAt": "2024-06-01T10:00:00.000Z"
  },
  "rawKey": "gfac_a1b2c3d4e5f6..."
}

Important : Le champ rawKey n'est retourné qu'à la création. Conservez-le en sécurité.

Scopes

Chaque clé API a des scopes qui limitent ses permissions :

Scope	Description
automation:read	Lister et consulter les automations
automation:write	Créer, modifier, supprimer des automations
automation:execute	Déclencher et arrêter des automations
pipeline:read	Lister et consulter les pipelines
pipeline:write	Créer, modifier, supprimer des pipelines
pipeline:execute	Déclencher et arrêter des pipelines
audit:read	Consulter les logs d'audit

Une requête nécessitant un scope que la clé ne possède pas retournera une erreur 403 Forbidden.

Gérer les clés

# Lister
GET /api-keys
 
# Détail
GET /api-keys/:id
 
# Mettre à jour (nom, isActive)
PATCH /api-keys/:id
 
# Supprimer
DELETE /api-keys/:id

Ces endpoints nécessitent un JWT Bearer token (pas une API key).

Expiration et désactivation

• Les clés peuvent avoir une date d'expiration (expiresAt)
• Les clés peuvent être désactivées via PATCH /api-keys/:id avec { "isActive": false }
• Le champ lastUsedAt est mis à jour à chaque utilisation