Authentification

Toutes les requêtes API Archyl nécessitent une authentification via une clé API. Ce guide explique comment créer et utiliser les clés API.

Créer une Clé API

Connectez-vous à votre compte Archyl
Allez dans Profil > Clés API
Cliquez sur Créer une Clé API
Configurez votre clé :
- Nom : Un nom descriptif (ex : "Pipeline CI/CD", "Développement Local")
- Permissions : Lecture seule ou Lecture-Écriture
- Expiration : Date d'expiration optionnelle
Cliquez sur Créer
Copiez et sauvegardez la clé immédiatement - elle ne sera plus affichée

Permissions des Clés API

Permission	Capacités
Lecture	Voir projets, éléments, documentation et données d'architecture
Écriture	Créer, modifier et supprimer projets, éléments et documentation

Choisissez les permissions minimales requises pour votre cas d'utilisation.

Utiliser Votre Clé API

Incluez votre clé API dans l'en-tête X-API-Key avec chaque requête :

curl -H "X-API-Key: votre-cle-api" \
  https://api.archyl.com/api/v1/projects

Exemple : Lister les Projets

curl -X GET \
  -H "X-API-Key: votre-cle-api" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

Exemple : Créer un Système

curl -X POST \
  -H "X-API-Key: votre-cle-api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service de Paiement",
    "description": "Gère le traitement des paiements",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Authentification du Serveur MCP

Lors de l'utilisation du Serveur MCP avec les assistants IA, l'authentification fonctionne de la même manière :

Claude Code / Claude Desktop

Ajoutez votre clé API à la configuration MCP :

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "votre-cle-api"
      }
    }
  }
}

Cursor

Dans .cursor/mcp.json :

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "votre-cle-api"
      }
    }
  }
}

Bonnes Pratiques de Sécurité

Protégez Vos Clés

Ne committez jamais les clés API dans le contrôle de version
Utilisez des variables d'environnement dans les pipelines CI/CD
Faites tourner les clés périodiquement
Utilisez des clés séparées pour différents environnements

Variables d'Environnement

# Stocker dans .env (ajouter à .gitignore)
ARCHYL_API_KEY=votre-cle-api

# Utiliser dans les scripts
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

Intégration CI/CD

Stockez votre clé API comme secret dans votre plateforme CI/CD :

GitHub Actions :

- name: Mettre à jour l'Architecture
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI :

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Gérer les Clés API

Voir les Clés

Allez dans Profil > Clés API pour voir toutes vos clés actives :

Nom et date de création de la clé
Niveau de permission
Statut d'expiration
Horodatage de dernière utilisation

Révoquer des Clés

Pour révoquer une clé compromise ou inutilisée :

Allez dans Profil > Clés API
Trouvez la clé à révoquer
Cliquez sur Révoquer
Confirmez l'action

Les clés révoquées sont immédiatement invalidées.

Expiration des Clés

Les clés peuvent être configurées pour expirer :

Jamais : La clé reste valide jusqu'à révocation manuelle
30 jours : Bon pour un accès temporaire
90 jours : Équilibre entre sécurité et commodité
Personnalisé : Définir n'importe quelle date d'expiration

Réponses d'Erreur

Clé Invalide ou Manquante

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Clé API invalide ou manquante"
  }
}

Statut HTTP : 401 Non Autorisé

Permissions Insuffisantes

{
  "error": {
    "code": "FORBIDDEN",
    "message": "La clé API n'a pas les permissions d'écriture"
  }
}

Statut HTTP : 403 Interdit

Clé Expirée

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "La clé API a expiré"
  }
}