Aller au contenu

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.

RéférenceDéveloppeur
Voir en Markdown

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émentValeur
Préfixesk_
Longueursk_ suivi de 40 caractères (lettres, chiffres, - et _)
En-têtex-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
ApplicationLa clé compte comme émise pour cette application ; elle est refusée sur toute autre application
Environnementdev, 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)
ClientLes listes sont limitées à ce client, quels que soient les filtres envoyés
ProfilLes droits applicatifs de la clé sont ceux de ce profil, lus dans la matrice profils × droits de l'environnement de la clé
Niveau d'administrationNiveau minimal exigé par les endpoints, au plus celui de la personne qui a créé la clé
Adresses IP autoriséesOptionnel : un appel depuis une autre adresse est refusé
Date d'expirationOptionnelle : après cette date, la clé est refusée
ÉtatUne 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 :

  1. le client de la clé ;
  2. à défaut, son réseau, pour un compte technique de niveau Administrateur réseau ;
  3. à 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é :

EndpointPage
GET /api/legal-documentsDocuments légaux
GET /api/legal-documents/defaultDocuments légaux
POST /api/legal-documents/{id}/renderDocuments 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

Bash
curl -s "https://api.wakastart.app/api/config/teams" \
  -H "x-api-key: sk_test_exemple"
TypeScript
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

StatutMessageCause
401Authentification 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
401Cle API manquante (header x-api-key)L'endpoint exige une clé et la requête n'en porte pas
401Cle API utilisateur invalide ou expireeL'endpoint exige une clé et celle envoyée est refusée
403API key without tenant scope cannot list tenant dataClé sans client, réseau ni application
403Droit applicatif requis : <code>Le profil de la clé ne porte pas le droit
403Access denied: token authorized party does not match the target applicationClé d'une autre application
400Environment is deduced from the caller and cannot be providedParamètre env, envType ou envs envoyé
403Environment cannot be deduced: API key has no environmentClé 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é dev ou staging se 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érationsAuthentification
Vérification par votre wakapp : introspect, user-contextClé 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évocationJeton 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 :

JSON
{
  "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

ChampTypeDescription
widchaîneIdentifiant public de la clé. Jamais le secret
namechaîneNom
descriptionchaîne ou nullDescription
typechaîneUSER_BOUND (liée à un utilisateur) ou TECHNICAL
customerobjetOrganisme de la clé : { wid, name }
appobjetApplication : { wid, name }
envTypechaînedev, staging ou prod
ownerobjet ou nullClé liée : son utilisateur, { wid, label }. Clé technique : null
createdByobjetCréateur : { wid, label, deleted } ; deleted vaut true si son compte a été supprimé
rightstableau de chaînesDroits inscrits sur la clé
inoperantRightstableau de chaînesDroits inscrits mais sans effet : l'utilisateur ne les détient plus, ou ils ne sont plus disponibles dans l'environnement
statuschaîneACTIVE, SUSPENDED ou REVOKED
expiresAtchaîne ISO 8601 ou nullÉchéance ; null pour une validité infinie. Une clé échue est refusée
lastUsedAtchaîne ISO 8601 ou nullDernier usage accepté
createdAtchaîne ISO 8601Date de création

Le secret (secret, commençant par wsk_) n'est renvoyé qu'à la création et à la rotation.

Vérifier une clé

POST/api/app-keys/introspect

Authentification : clé sk_ de votre wakapp, sans Authorization. Appelée par votre wakapp à chaque requête d'un client.

ChampTypeObligatoireDescription
secretchaîneouiSecret wsk_ présenté par le client
Bash
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 :

JSON
{
  "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
}
ChampDescription
activetrue si la clé est acceptée ; sinon la réponse est { "active": false }, sans autre champ
key_idIdentifiant public de la clé, à écrire dans vos journaux
typeUSER_BOUND ou TECHNICAL
ownerClé liée : { "wid": "…" } de son utilisateur. Clé technique : null
customerOrganisme de la clé. Limitez toutes vos requêtes à cet organisme
app, envWID de votre application et environnement de la clé
rightsDroits 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
expExpiration en secondes depuis l'epoch, null pour une validité infinie
context_tokenFacultatif : 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

POST/api/app-keys/user-context

Authentification : 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.

ChampTypeObligatoireDescription
userTokenchaîneouiJeton d'accès Keycloak de l'utilisateur, émis pour votre wakapp
Bash
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 :

JSON
{ "context_token": "eyJhbGciOiJFZERTQSJ9.exemple", "exp": 1798790460 }

Erreurs

StatutCode
401USER_TOKEN_INVALID : jeton refusé (signature, expiration) ou identité ambiguë
403AZP_MISMATCH : jeton émis pour une autre application
403USER_TOKEN_ENV_MISMATCH : jeton d'un autre environnement que votre clé sk_
403USER_NOT_MEMBER : utilisateur ou organisme inactif, ou sans accès à l'application
503CONTEXT_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é

POST/api/app-keys

Qui : 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.

ChampTypeObligatoireContraintesDescription
typechaîneouiUSER_BOUND ou TECHNICALType de clé
namechaîneoui—Nom
descriptionchaînenon—Description
rightstableau de chaînesouiDroits du catalogue, sous le plafond de l'appelantDroits accordés
validitychaînenon30d, 90d, 1y, infiniteValidité ; 1y par défaut
customerWidchaînepour une clé technique—Organisme de la clé technique
Bash
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

GET/api/app-keys

Qui : 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êteTypeDéfautDescription
minebooléen—true : seulement les clés liées à l'appelant
customerWidchaîne—Organisme
typechaîne—USER_BOUND ou TECHNICAL
statuschaîne—ACTIVE, SUSPENDED ou REVOKED
limitentier500Taille de page, 500 au plus
offsetentier0Décalage

Réponse : { "data": [Clé…], "total": 12 }. total compte toutes les clés visibles, pas seulement la page.

Lire les droits attribuables

GET/api/app-keys/assignable-rights

Droits 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é

GET/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é

PATCH/api/app-keys/{wid}

Qui : le propriétaire, les administrateurs de l'organisme. Le plafond s'applique à addRights ; retirer un droit est toujours permis.

ChampTypeDescription
namechaîneNouveau nom
descriptionchaîneNouvelle description
addRightstableau de chaînesDroits à ajouter
removeRightstableau de chaînesDroits à 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

POST/api/app-keys/{wid}/rotate

Qui : 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é

DELETE/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érationLimite par défaut
POST /api/app-keys/introspect3 000 appels par minute
POST /api/app-keys/user-context600 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.