Clés API
Clés sk_ (format, portée, droits, erreurs) et opérations /api/app-keys des clés wsk_ que vos clients utilisent pour appeler votre wakapp.
Une clé API authentifie les appels d'un serveur, sans utilisateur connecté. Elle s'envoie dans l'en-tête x-api-key. Cette page décrit ce qu'une clé permet ; la création et la gestion des clés sont décrites dans Clés API. Les clés wsk_ que les organismes clients utilisent pour appeler votre wakapp sont décrites plus bas, dans Clés API de votre wakapp.
Obtenir une clé
Les clés API sont créées par l'équipe Wakastart. Pour en obtenir une, indiquez l'application, l'environnement, le client et le profil voulus. La clé complète ne vous est montrée qu'une seule fois : rangez-la aussitôt dans un secret de votre service. Wakastart n'en conserve qu'une empreinte et ses 10 premiers caractères, qui permettent de la reconnaître.
L'API publique n'expose aucun endpoint de création, de lecture ou de révocation de clé sk_.
Format
| Élément | Valeur |
|---|---|
| Préfixe | sk_ |
| Longueur | sk_ suivi de 40 caractères (lettres, chiffres, - et _) |
| En-tête | x-api-key: sk_… |
Un en-tête x-api-key dont la valeur ne commence pas par sk_ n'est pas reconnu comme une clé de votre organisation.
Ce que porte une clé
| Propriété | Effet sur les appels |
|---|---|
| Application | La clé compte comme émise pour cette application ; elle est refusée sur toute autre application |
| Environnement | dev, staging ou prod. Les appels s'exécutent dans cet environnement, que vous ne fournissez jamais : les utilisateurs lus ou modifiés sont ceux de cet environnement, une invitation créée par la clé vaut pour cet environnement. Un paramètre env, envType ou envs est refusé (400) |
| Client | Les listes sont limitées à ce client, quels que soient les filtres envoyés |
| Profil | Les droits applicatifs de la clé sont ceux de ce profil, lus dans la matrice profils × droits de l'environnement de la clé |
| Niveau d'administration | Niveau minimal exigé par les endpoints, au plus celui de la personne qui a créé la clé |
| Adresses IP autorisées | Optionnel : un appel depuis une autre adresse est refusé |
| Date d'expiration | Optionnelle : après cette date, la clé est refusée |
| État | Une clé désactivée ou révoquée est refusée immédiatement |
Une clé peut être liée à un compte utilisateur ou être un compte technique, sans utilisateur. Une clé de compte technique n'a pas d'identité de personne : GET /api/me lui répond 404 Utilisateur non trouvé.
Portée des listes
Pour un appel par clé, l'API remplace les filtres de portée de la requête (customerWid, networkWid…) par la portée de la clé, dans cet ordre :
- le client de la clé ;
- à défaut, son réseau, pour un compte technique de niveau Administrateur réseau ;
- à défaut, son application.
Une clé sans aucune de ces portées ne peut rien lister : 403 API key without tenant scope cannot list tenant data.
Endpoints qui exigent une clé
La plupart des endpoints acceptent indifféremment un jeton ou une clé. Les endpoints suivants n'acceptent que une clé :
| Endpoint | Page |
|---|---|
GET /api/legal-documents | Documents légaux |
GET /api/legal-documents/default | Documents légaux |
POST /api/legal-documents/{id}/render | Documents légaux |
À l'inverse, les endpoints de paiement de l'utilisateur final (/api/billing/*) exigent l'identité d'un utilisateur de l'application ; une clé de compte technique n'y convient pas.
Exemple
curl -s "https://api.wakastart.app/api/config/teams" \
-H "x-api-key: sk_test_exemple"const WAKASTART_API_KEY = process.env.WAKASTART_API_KEY; // lue dans un secret, jamais dans le code
const res = await fetch("https://api.wakastart.app/api/config/teams", {
headers: { "x-api-key": WAKASTART_API_KEY! },
});
if (res.status === 401) throw new Error("Clé API refusée : vérifiez sa validité");
const { data } = await res.json();N'envoyez pas d'en-tête Authorization dans la même requête : la clé serait ignorée.
Erreurs
| Statut | Message | Cause |
|---|---|---|
401 | Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header) | Clé inconnue, inactive, expirée ou utilisée depuis une adresse IP non autorisée |
401 | Cle API manquante (header x-api-key) | L'endpoint exige une clé et la requête n'en porte pas |
401 | Cle API utilisateur invalide ou expiree | L'endpoint exige une clé et celle envoyée est refusée |
403 | API key without tenant scope cannot list tenant data | Clé sans client, réseau ni application |
403 | Droit applicatif requis : <code> | Le profil de la clé ne porte pas le droit |
403 | Access denied: token authorized party does not match the target application | Clé d'une autre application |
400 | Environment is deduced from the caller and cannot be provided | Paramètre env, envType ou envs envoyé |
403 | Environment cannot be deduced: API key has no environment | Clé sans environnement |
Bonnes pratiques
- Une clé par service et par environnement, pour pouvoir en révoquer une sans couper les autres. Les droits d'une clé
devoustagingse règlent dans la matrice de son environnement, indépendamment de la production. - Le profil le plus restreint possible : seulement les droits dont le service a besoin.
- Une date d'expiration et une liste d'adresses IP quand votre service sort par des adresses fixes.
- En cas de fuite, demandez la révocation immédiate de la clé, puis remplacez-la.
Clés API de votre wakapp
Bêta Ces opérations sont en cours de déploiement et ne répondent pas encore.
Les clés wsk_ permettent au système d'information d'un organisme client d'appeler l'API de votre wakapp. Elles portent des droits de votre catalogue et aucun droit sur Wakastart : une clé wsk_ envoyée à l'API publique reçoit un 401. Concepts et guides : Clés API de votre wakapp.
Deux familles d'opérations, avec deux authentifications :
| Opérations | Authentification |
|---|---|
Vérification par votre wakapp : introspect, user-context | Clé sk_ de votre wakapp dans x-api-key, sans Authorization. Wakastart en déduit votre application et votre environnement |
| Gestion des clés : création, liste, lecture, modification, rotation, révocation | Jeton de l'utilisateur dans Authorization: Bearer (et son x-enriched-token si vous l'avez), sans clé sk_ ; une clé seule est refusée (403 API_KEY_CANNOT_MANAGE_KEYS). Aucun droit Wakastart n'est exigé : le plafond et la portée sont vérifiés par Wakastart |
Pour la gestion, l'application et l'environnement sont déduits du jeton : l'application pour laquelle il a été émis, l'environnement de la session. Toutes ces opérations sont bornées à cette application et à cet environnement. appWid ou envType envoyé et différent répond 403 APP_SCOPE_MISMATCH ; un jeton qui ne désigne aucune application cliente répond 403 APP_NOT_RESOLVED ; une clé d'une autre application ou d'un autre environnement répond 404.
Les erreurs ont le format habituel, avec un code stable dans message et parfois un objet details :
{
"statusCode": 403,
"message": "RIGHTS_EXCEED_CEILING",
"error": "Forbidden",
"details": { "missing": ["formations.delete"] }
}La liste des codes est dans Codes d'erreur.
L'objet clé de wakapp
| Champ | Type | Description |
|---|---|---|
wid | chaîne | Identifiant public de la clé. Jamais le secret |
name | chaîne | Nom |
description | chaîne ou null | Description |
type | chaîne | USER_BOUND (liée à un utilisateur) ou TECHNICAL |
customer | objet | Organisme de la clé : { wid, name } |
app | objet | Application : { wid, name } |
envType | chaîne | dev, staging ou prod |
owner | objet ou null | Clé liée : son utilisateur, { wid, label }. Clé technique : null |
createdBy | objet | Créateur : { wid, label, deleted } ; deleted vaut true si son compte a été supprimé |
rights | tableau de chaînes | Droits inscrits sur la clé |
inoperantRights | tableau de chaînes | Droits inscrits mais sans effet : l'utilisateur ne les détient plus, ou ils ne sont plus disponibles dans l'environnement |
status | chaîne | ACTIVE, SUSPENDED ou REVOKED |
expiresAt | chaîne ISO 8601 ou null | Échéance ; null pour une validité infinie. Une clé échue est refusée |
lastUsedAt | chaîne ISO 8601 ou null | Dernier usage accepté |
createdAt | chaîne ISO 8601 | Date de création |
Le secret (secret, commençant par wsk_) n'est renvoyé qu'à la création et à la rotation.
Vérifier une clé
/api/app-keys/introspectAuthentification : clé sk_ de votre wakapp, sans Authorization. Appelée par votre wakapp à chaque requête d'un client.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
secret | chaîne | oui | Secret wsk_ présenté par le client |
curl -s -X POST https://api.wakastart.app/api/app-keys/introspect \
-H "x-api-key: sk_test_exemple" \
-H 'Content-Type: application/json' \
-d '{ "secret": "wsk_exemple3kTq9" }'Réponse 200, toujours, que la clé soit valide ou non :
{
"active": true,
"key_id": "K7hq2P",
"type": "TECHNICAL",
"owner": null,
"customer": { "wid": "ALPHA1", "name": "Organisme Alpha" },
"app": "APPEX1",
"env": "prod",
"rights": ["formations.read", "participants.invite"],
"exp": null
}| Champ | Description |
|---|---|
active | true si la clé est acceptée ; sinon la réponse est { "active": false }, sans autre champ |
key_id | Identifiant public de la clé, à écrire dans vos journaux |
type | USER_BOUND ou TECHNICAL |
owner | Clé liée : { "wid": "…" } de son utilisateur. Clé technique : null |
customer | Organisme de la clé. Limitez toutes vos requêtes à cet organisme |
app, env | WID de votre application et environnement de la clé |
rights | Droits effectifs : pour une clé liée, croisés avec les droits actuels de l'utilisateur ; pour une clé technique, bornés par les droits que l'organisme détient encore |
exp | Expiration en secondes depuis l'epoch, null pour une validité infinie |
context_token | Facultatif : jeton de contexte « clé client », valable 60 secondes |
{ "active": false } couvre une clé inconnue, révoquée, expirée, suspendue, d'une autre application, d'un autre environnement, ou dont l'organisme n'a plus l'application. Ne gardez jamais une réponse positive en cache.
Erreurs : 403 CALLER_APP_KEY_REQUIRED sans clé sk_ valide, 429 au-delà de la limite de débit, 503 APP_KEYS_UNAVAILABLE si Wakastart ne peut pas traiter la demande. Si Wakastart ne peut pas signer de contexte, la réponse n'a pas de context_token.
Obtenir un contexte utilisateur
/api/app-keys/user-contextAuthentification : clé sk_ de votre wakapp, sans Authorization. Renvoie un jeton de contexte « utilisateur », pour agir sur Wakastart avec votre clé au nom d'un utilisateur de votre wakapp.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
userToken | chaîne | oui | Jeton d'accès Keycloak de l'utilisateur, émis pour votre wakapp |
curl -s -X POST https://api.wakastart.app/api/app-keys/user-context \
-H "x-api-key: sk_test_exemple" \
-H 'Content-Type: application/json' \
-d '{ "userToken": "eyJhbGciOiJSUzI1NiJ9.exemple" }'Réponse 200 :
{ "context_token": "eyJhbGciOiJFZERTQSJ9.exemple", "exp": 1798790460 }Erreurs
| Statut | Code |
|---|---|
401 | USER_TOKEN_INVALID : jeton refusé (signature, expiration) ou identité ambiguë |
403 | AZP_MISMATCH : jeton émis pour une autre application |
403 | USER_TOKEN_ENV_MISMATCH : jeton d'un autre environnement que votre clé sk_ |
403 | USER_NOT_MEMBER : utilisateur ou organisme inactif, ou sans accès à l'application |
503 | CONTEXT_SIGNING_UNAVAILABLE : Wakastart ne peut pas signer de contexte pour le moment |
Présenter un contexte
Joignez le jeton de contexte à un appel de l'API publique dans l'en-tête X-WakaStart-Context, avec votre clé sk_ dans x-api-key et sans en-tête Authorization. Il vaut 60 secondes au plus. L'exigence de contexte est réglée par type d'action et par application (observe, preferred, required, bound) : voir Jeton de contexte. Les refus sont listés dans Codes d'erreur.
Créer une clé
/api/app-keysQui : clé liée, tout utilisateur actif qui a accès à l'application dans cet environnement, pour lui-même ; clé technique, un administrateur de l'organisme.
| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
type | chaîne | oui | USER_BOUND ou TECHNICAL | Type de clé |
name | chaîne | oui | — | Nom |
description | chaîne | non | — | Description |
rights | tableau de chaînes | oui | Droits du catalogue, sous le plafond de l'appelant | Droits accordés |
validity | chaîne | non | 30d, 90d, 1y, infinite | Validité ; 1y par défaut |
customerWid | chaîne | pour une clé technique | — | Organisme de la clé technique |
curl -s -X POST https://api.wakastart.app/api/app-keys \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "type": "USER_BOUND", "name": "Export compta", "rights": ["formations.read"], "validity": "1y" }'Réponse 201 : l'objet clé et son secret, renvoyé cette seule fois.
Lister les clés
/api/app-keysQui : le propriétaire de ses clés liées, les administrateurs de l'organisme pour les clés de leur portée. Renvoie les clés de l'application et de l'environnement du jeton, jamais de secret.
| Paramètre de requête | Type | Défaut | Description |
|---|---|---|---|
mine | booléen | — | true : seulement les clés liées à l'appelant |
customerWid | chaîne | — | Organisme |
type | chaîne | — | USER_BOUND ou TECHNICAL |
status | chaîne | — | ACTIVE, SUSPENDED ou REVOKED |
limit | entier | 500 | Taille de page, 500 au plus |
offset | entier | 0 | Décalage |
Réponse : { "data": [Clé…], "total": 12 }. total compte toutes les clés visibles, pas seulement la page.
Lire les droits attribuables
/api/app-keys/assignable-rightsDroits que l'appelant peut donner à une clé : ceux du catalogue de l'application disponibles dans l'environnement, qu'il détient lui-même. Paramètres : type (USER_BOUND ou TECHNICAL) et, pour une clé technique, customerWid ; un organisme hors de la portée d'administration de l'appelant répond 404.
Réponse : { "data": [{ "code": "formations.read", "name": "Lire les formations", "category": "Formations" }] }. Cette liste sert à l'affichage : le plafond est revérifié à la création.
Lire une clé
/api/app-keys/{wid}Qui : le propriétaire, les administrateurs de l'organisme. Réponse : l'objet clé. Une clé hors de la portée de l'appelant répond 404.
Modifier une clé
/api/app-keys/{wid}Qui : le propriétaire, les administrateurs de l'organisme. Le plafond s'applique à addRights ; retirer un droit est toujours permis.
| Champ | Type | Description |
|---|---|---|
name | chaîne | Nouveau nom |
description | chaîne | Nouvelle description |
addRights | tableau de chaînes | Droits à ajouter |
removeRights | tableau de chaînes | Droits à retirer |
Le type, l'organisme, l'application et l'environnement ne se modifient pas (400 IMMUTABLE_FIELD). Une clé révoquée ne se modifie plus (409 KEY_REVOKED).
Faire tourner le secret
/api/app-keys/{wid}/rotateQui : le propriétaire seul pour une clé liée ; un administrateur de l'organisme pour une clé technique, si les droits de la clé restent sous son propre plafond.
Réponse 200 : l'objet clé et son nouveau secret, renvoyé une seule fois. L'ancien secret reste valable 7 jours au plus, jamais au-delà de l'échéance de la clé. Une nouvelle rotation pendant ce délai coupe immédiatement le secret qui était déjà en sursis : seuls le nouveau secret et le précédent restent valides.
Révoquer une clé
/api/app-keys/{wid}Qui : le propriétaire, les administrateurs de l'organisme. Corps facultatif : { "reason": "plus utilisée" }.
Réponse 204. La révocation est immédiate : la clé est refusée dès l'introspection suivante et reste consultable au statut REVOKED.
Limites de débit
| Opération | Limite par défaut |
|---|---|
POST /api/app-keys/introspect | 3 000 appels par minute |
POST /api/app-keys/user-context | 600 appels par minute |
Ces limites sont comptées par wakapp et par environnement de sa clé sk_, sur une fenêtre fixe d'une minute, et par instance du service Wakastart : chaque instance tient ses propres compteurs, la limite effective est donc multipliée par le nombre d'instances. Au-delà, la réponse est 429 avec l'en-tête Retry-After, en secondes.