# Clés API

> Les clés sk_ de vos serveurs pour appeler l'API publique Wakastart, et les clés wsk_ que vos clients utilisent pour appeler l'API de votre wakapp.

Une [clé API](/v1.0/glossaire#clé-api) permet à un serveur d'appeler l'API publique Wakastart sans utilisateur connecté : synchroniser des comptes depuis votre système, envoyer des invitations, lire les utilisateurs d'un client. La clé est rattachée à une application, à un environnement et à un client, et ses droits viennent d'un profil.

Wakastart gère aussi une seconde famille de clés, celles que les **organismes clients de votre wakapp** utilisent pour appeler l'API de votre wakapp depuis leur propre système d'information. Ces clés `wsk_` portent des droits de votre catalogue, aucun droit sur Wakastart : voir [Clés de votre wakapp](#clés-de-votre-wakapp).

## Comment ça marche

```mermaid
flowchart LR
  S["Votre serveur"] -- "x-api-key: sk_…" --> A["API publique<br/>api.wakastart.app/api"]
  A -- "empreinte SHA-256" --> V{"Clé active ?<br/>non expirée ?<br/>adresse IP autorisée ?"}
  V -- "oui" --> C["Contexte de la clé :<br/>application, environnement,<br/>client, niveau, droits du profil"]
  C --> O["Opération exécutée<br/>dans ce périmètre"]
  V -- "non" --> E["401"]
```

Wakastart ne conserve que l'empreinte de la clé. À chaque appel, l'API retrouve la clé par cette empreinte, vérifie qu'elle est active, non expirée et utilisée depuis une adresse autorisée, puis exécute l'opération avec le niveau et les droits de la clé, dans le périmètre de son client. Le détail est dans [Fonctionnement des clés API](/v1.0/cles-api/fonctionnement-des-cles-api).

## Choisissez votre approche

::::cards{cols=2}
:::card{title="Clé technique" href="/v1.0/cles-api/fonctionnement-des-cles-api" icon="Server"}
Recommandé pour un backend : la clé n'appartient à aucune personne et agit pour un client.
:::
:::card{title="Jeton de l'utilisateur" href="/v1.0/authentification/jetons-et-sessions" icon="UserCheck"}
Quand l'action est faite au nom d'un utilisateur connecté, transmettez plutôt son jeton Keycloak.
:::
::::

## Commencer

::::cards{cols=3}
:::card{title="Obtenir une clé" href="/v1.0/cles-api/obtenir-une-cle-api" icon="KeyRound"}
Ce qu'il faut préciser pour recevoir une clé adaptée à votre usage.
:::
:::card{title="Appeler l'API" href="/v1.0/cles-api/appeler-l-api-avec-une-cle" icon="Terminal"}
Un premier appel en cURL et en TypeScript.
:::
:::card{title="Stocker la clé" href="/v1.0/cles-api/stocker-une-cle-en-securite" icon="Lock"}
La ranger dans un secret, jamais dans le code.
:::
::::

## Clés de votre wakapp

:badge[Bêta]{type=beta} En cours de déploiement, pas encore disponible.

| | Clé `sk_` | Clé de votre wakapp |
|---|---|---|
| Utilisée par | Votre serveur | Le système d'information d'un organisme client |
| Pour appeler | L'API publique Wakastart | L'API de votre wakapp |
| Droits | Profil et niveau Wakastart | Droits du catalogue de votre application |

::::cards{cols=3}
:::card{title="Clés API de votre wakapp" href="/v1.0/cles-api/cles-api-de-votre-wakapp" icon="KeyRound"}
Types, plafond des droits, validité, rotation et révocation.
:::
:::card{title="Gérer les clés dans la console" href="/v1.0/cles-api/gerer-les-cles-de-votre-wakapp" icon="LayoutDashboard"}
L'onglet Clés API de l'app : créer, modifier, faire tourner, révoquer.
:::
:::card{title="Vérifier une clé" href="/v1.0/cles-api/verifier-une-cle-de-votre-wakapp" icon="ShieldCheck"}
L'introspection et le kit pour protéger les routes de votre wakapp.
:::
:::card{title="Proposer les clés dans votre wakapp" href="/v1.0/cles-api/proposer-les-cles-dans-votre-wakapp" icon="UserCog"}
Un écran « Mes clés API » au nom de l'utilisateur connecté.
:::
:::card{title="Jeton de contexte" href="/v1.0/cles-api/jeton-de-contexte" icon="Workflow"}
Borner à l'organisme du client une action faite avec votre clé sk_.
:::
:::card{title="Agir sur Wakastart pour un client" href="/v1.0/cles-api/agir-sur-wakastart-pour-un-client" icon="Send"}
Inviter un apprenant depuis l'appel d'un client, en toute sécurité.
:::
::::

## Fonctionnalités

::::cards{cols=3}
:::card{title="Profil et droits" href="/v1.0/cles-api/fonctionnement-des-cles-api" icon="ShieldCheck"}
Les droits de la clé sont ceux de son profil, ni plus ni moins.
:::
:::card{title="Restriction d'adresses IP" href="/v1.0/cles-api/reference" icon="Network"}
Limiter l'usage de la clé aux adresses de vos serveurs.
:::
:::card{title="Expiration" href="/v1.0/cles-api/faire-tourner-une-cle" icon="CalendarClock"}
Donner une date de fin à la clé et la remplacer sans coupure.
:::
:::card{title="Révocation" href="/v1.0/cles-api/revoquer-une-cle" icon="Ban"}
Désactiver ou supprimer une clé compromise.
:::
:::card{title="Traçabilité" href="/v1.0/journal-d-audit" icon="ScrollText"}
Création, activation et révocation sont tracées dans le journal d'audit.
:::
:::card{title="Mise en production" href="/v1.0/cles-api/liste-de-controle" icon="ListChecks"}
Les vérifications avant de brancher une clé de production.
:::
::::

## Produits liés

::::cards{cols=3}
:::card{title="Droits et profils" href="/v1.0/droits-et-profils" icon="ShieldCheck"}
Les droits applicatifs qu'un profil accorde.
:::
:::card{title="Variables et secrets" href="/v1.0/variables-et-secrets" icon="Lock"}
Fournir la clé à un service hébergé sur Wakastart.
:::
:::card{title="Utilisateurs et équipes" href="/v1.0/utilisateurs" icon="Users"}
Inviter des utilisateurs depuis votre backend.
:::
::::

## Ressources

- [Référence des clés API](/v1.0/cles-api/reference) et [Référence API : Clés API](/v1.0/reference-api/cles-api).
- [Résoudre les problèmes de clés API](/v1.0/cles-api/depannage).
- [Limites et quotas](/v1.0/limites).
