Aller au contenu

Référence des clés API

Format d'une clé API, attributs, règles de validation, contexte transmis à l'API, erreurs et limites.

RéférenceDéveloppeur
Voir en Markdown

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émentValeur
Formesk_ suivi de 40 caractères (lettres, chiffres, - et _)
Préfixe affichéLes 10 premiers caractères, par exemple sk_test_ex
ConservationEmpreinte SHA-256 uniquement ; la clé complète n'est affichée qu'à la création
En-têtex-api-key: sk_…
URL de basehttps://api.wakastart.app/api

L'objet clé API

AttributDescription
Nom100 caractères au plus
Description1 000 caractères au plus
ApplicationApplication sur laquelle la clé agit
Environnementdev, staging ou prod
ClientClient dans le périmètre duquel la clé agit
UtilisateurVide pour une clé technique ; sinon l'utilisateur auquel la clé est liée
ProfilProfil dont la clé reçoit les droits applicatifs
Niveau d'administrationPARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN ou aucun
Adresses IP autoriséesListe vide : toutes les adresses ; sinon adresses IPv4 exactes et blocs /24 ou /16
ExpirationDate ISO 8601 ; vide : sans expiration
Activetrue ou false
Dernier usageDate 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 :

  1. la clé existe (son empreinte est connue) ;
  2. elle est active ;
  3. sa date d'expiration n'est pas dépassée ;
  4. 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émentClé techniqueClé liée à un compte
Application, identifiant client (azp)Application de la cléApplication de la clé
EnvironnementCelui de la cléCelui de la clé
ClientCelui de la cléCelui de l'utilisateur
Niveau d'administrationCelui de la clé, sinon aucunCelui de la clé, sinon celui de l'utilisateur
Droits applicatifsDroits du profil de la clé, lus dans la matrice profils × droits de l'environnement de la cléIdem
RéseauTransmis pour une clé de niveau NETWORK_ADMINNon transmis
Adresse e-mailAucuneCelle 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

StatutMessageCause
401Cle API utilisateur invalide ou expireeClé inconnue, révoquée, désactivée, expirée, ou adresse IP non autorisée
401Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)Aucun en-tête d'authentification
403Droit applicatif requis : <code>Le profil de la clé ne porte pas le droit exigé
403Niveau d'administration insuffisant. Requis: <niveau>, Actuel: <niveau>Niveau de la clé insuffisant
400Environment is deduced from the caller and cannot be providedLa requête porte un paramètre env, envType ou envs
403Environment cannot be deduced: API key has no environmentClé sans environnement
429ThrottlerException: Too Many RequestsLimite de débit par adresse IP dépassée

Limites

ÉlémentValeur
Débit de l'API publique, par adresse IP10 requêtes/s, 100 requêtes/min, 1 000 requêtes/h
Plages d'adresses IPIPv4 exacte, /24, /16
Taille d'un corps JSON1 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).

GET/api/config/users

Exemple 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.