Référence des clés API
Format d'une clé API, attributs, règles de validation, contexte transmis à l'API, erreurs et limites.
This page has not been translated yet and is shown in French.
Cette page décrit l'objet clé API et son comportement dans l'API publique. Les opérations de l'API publique qui acceptent une clé sont détaillées dans la référence API.
Format
| Élément | Valeur |
|---|---|
| Forme | sk_ suivi de 40 caractères (lettres, chiffres, - et _) |
| Préfixe affiché | Les 10 premiers caractères, par exemple sk_test_ex |
| Conservation | Empreinte SHA-256 uniquement ; la clé complète n'est affichée qu'à la création |
| En-tête | x-api-key: sk_… |
| URL de base | https://api.wakastart.app/api |
L'objet clé API
| Attribut | Description |
|---|---|
| Nom | 100 caractères au plus |
| Description | 1 000 caractères au plus |
| Application | Application sur laquelle la clé agit |
| Environnement | dev, staging ou prod |
| Client | Client dans le périmètre duquel la clé agit |
| Utilisateur | Vide pour une clé technique ; sinon l'utilisateur auquel la clé est liée |
| Profil | Profil dont la clé reçoit les droits applicatifs |
| Niveau d'administration | PARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN ou aucun |
| Adresses IP autorisées | Liste vide : toutes les adresses ; sinon adresses IPv4 exactes et blocs /24 ou /16 |
| Expiration | Date ISO 8601 ; vide : sans expiration |
| Active | true ou false |
| Dernier usage | Date et adresse IP du dernier appel accepté |
Une clé ne se modifie pas après sa création, sauf son état actif.
Validation à chaque appel
L'API refuse la clé si l'une de ces conditions n'est pas remplie :
- la clé existe (son empreinte est connue) ;
- elle est active ;
- sa date d'expiration n'est pas dépassée ;
- l'adresse IP d'appel figure dans sa liste autorisée, si elle en a une.
L'en-tête x-api-key n'est pris en compte qu'en l'absence d'en-tête Authorization.
Contexte de l'appel
| Élément | Clé technique | Clé liée à un compte |
|---|---|---|
Application, identifiant client (azp) | Application de la clé | Application de la clé |
| Environnement | Celui de la clé | Celui de la clé |
| Client | Celui de la clé | Celui de l'utilisateur |
| Niveau d'administration | Celui de la clé, sinon aucun | Celui de la clé, sinon celui de l'utilisateur |
| Droits applicatifs | Droits du profil de la clé, lus dans la matrice profils × droits de l'environnement de la clé | Idem |
| Réseau | Transmis pour une clé de niveau NETWORK_ADMIN | Non transmis |
| Adresse e-mail | Aucune | Celle de l'utilisateur |
Une opération qui exige un utilisateur, comme GET /api/me, n'a pas de sens avec une clé technique.
L'environnement de l'appel est toujours celui de la clé : un paramètre env, envType ou envs envoyé à l'API publique est refusé.
Clés de votre wakapp
Les clés wsk_ que les organismes clients utilisent pour appeler l'API de votre wakapp sont un objet distinct, géré par l'onglet Clés API de l'app de la console ou par les opérations /api/app-keys. Leur objet, leurs statuts, leurs opérations et leurs limites de débit sont décrits dans la référence API, et leurs codes d'erreur dans Codes d'erreur.
Erreurs
| Statut | Message | Cause |
|---|---|---|
401 | Cle API utilisateur invalide ou expiree | Clé inconnue, révoquée, désactivée, expirée, ou adresse IP non autorisée |
401 | Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header) | Aucun en-tête d'authentification |
403 | Droit applicatif requis : <code> | Le profil de la clé ne porte pas le droit exigé |
403 | Niveau d'administration insuffisant. Requis: <niveau>, Actuel: <niveau> | Niveau de la clé insuffisant |
400 | Environment is deduced from the caller and cannot be provided | La requête porte un paramètre env, envType ou envs |
403 | Environment cannot be deduced: API key has no environment | Clé sans environnement |
429 | ThrottlerException: Too Many Requests | Limite de débit par adresse IP dépassée |
Limites
| Élément | Valeur |
|---|---|
| Débit de l'API publique, par adresse IP | 10 requêtes/s, 100 requêtes/min, 1 000 requêtes/h |
| Plages d'adresses IP | IPv4 exacte, /24, /16 |
| Taille d'un corps JSON | 1 Mo |
Opérations
Il n'existe pas d'opération de l'API publique pour créer, lister ou révoquer des clés sk_ : elles sont émises et révoquées par l'équipe Wakastart (voir Obtenir une clé API).
/api/config/usersExemple d'opération appelée avec une clé : liste des utilisateurs du client de la clé. Exige le niveau Administrateur client et le droit users.read. Détail : Référence API : Utilisateurs.
Toutes les opérations de l'API publique qui ne sont pas publiques acceptent une clé, dans la limite de ses droits. Voir Référence API : Clés API et Authentification de l'API.