Clés API

Les clés API fournissent une méthode d'authentification sécurisée et à longue durée de vie pour l'accès programmatique à l'API Avatar. Elles sont idéales pour les pipelines automatisés, les intégrations CI/CD et la communication entre services où la connexion interactive n'est pas envisageable.

Présentation

Contrairement à l'authentification par identifiant/mot de passe qui produit des jetons JWT à courte durée de vie, les clés API :

• Sont à longue durée de vie avec une expiration configurable (30 à 3 650 jours)
• Peuvent être révoquées à tout moment sans affecter le mot de passe de l'utilisateur
• Sont rattachées à un utilisateur et héritent de ses permissions
• Sont adaptées aux workflows automatisés/sans interface

Créer une clé API

Client Python

import httpx

client = httpx.Client(base_url="https://votre-instance-avatar.com/api")
# D'abord s'authentifier avec identifiant/mot de passe
response = client.post("/login", json={"username": "user@example.com", "password": "votre-mot-de-passe"})
token = response.json()["access_token"]

# Créer une clé API
response = client.post(
    "/api-keys",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "mon-pipeline-etl",
        "expiration_days": 365
    }
)
api_key = response.json()
print(f"Clé API : {api_key['key']}")  # Sauvegardez-la — elle ne sera plus affichée

Paramètres

Paramètre	Type	Requis	Description
name	string	Oui	Un nom descriptif pour la clé (256 caractères maximum)
expiration_days	integer	Oui	Durée de vie de la clé. Valeurs autorisées : 30, 60, 120, 365, 3650

attention

La valeur complète de la clé API n'est renvoyée qu'une seule fois lors de la création. Conservez-la en lieu sûr — elle ne pourra pas être récupérée ultérieurement.

Utiliser une clé API

Une fois créée, envoyez la clé API dans l'en-tête Authorization avec le schéma api-key-v1 :

curl -H "Authorization: api-key-v1 <votre-cle-api>" \
  https://votre-instance-avatar.com/api/health

import httpx

client = httpx.Client(
    base_url="https://votre-instance-avatar.com/api",
    headers={"Authorization": "api-key-v1 <votre-cle-api>"}
)
response = client.get("/health")

Gérer les clés API

Lister toutes les clés

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

GET /api-keys

Renvoie les métadonnées des clés (nom, date de création, expiration) mais pas la valeur de la clé elle-même.

Obtenir les détails d'une clé

GET /api-keys/{api_key_id}

Révoquer une clé spécifique

DELETE /api-keys/{api_key_id}

Révoquer toutes les clés

Révoquez toutes les clés API associées à votre compte :

DELETE /api-keys

Admin : Révoquer les clés d'autres utilisateurs

Les administrateurs peuvent révoquer des clés par identifiant utilisateur ou identifiant de clé :

DELETE /api-keys/admin?user_id={user_id}
DELETE /api-keys/admin?api_key_id={api_key_id}

Politiques d'expiration

Durée	Jours	Utilisation recommandée
1 mois	30	Accès temporaire, tests
2 mois	60	Projets à court terme
4 mois	120	Rotation trimestrielle
1 an	365	Automatisation standard
10 ans	3 650	Comptes de service à longue durée

astuce

Nous recommandons de renouveler les clés API régulièrement. Utilisez des périodes d'expiration plus courtes pour les clés avec un accès étendu et des périodes plus longues pour les automatisations à périmètre restreint.

Bonnes pratiques de sécurité

• Ne committez jamais de clés API dans le contrôle de version
• Utilisez des variables d'environnement pour stocker les clés dans les pipelines automatisés
• Renouvelez les clés régulièrement et révoquez celles qui ne sont plus utilisées
• Utilisez des noms descriptifs pour identifier facilement l'usage de chaque clé
• Surveillez l'utilisation via le panneau d'administration pour détecter les anomalies