# Référence des clés API

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

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](/v1.0/reference-api/cles-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 :

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é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](/v1.0/reference-api/cles-api#clés-api-de-votre-wakapp), et leurs codes d'erreur dans [Codes d'erreur](/v1.0/codes-d-erreur#clés-api-des-wakapps).

## 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](/v1.0/cles-api/obtenir-une-cle-api)).

::endpoint{method="GET" path="/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](/v1.0/reference-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](/v1.0/reference-api/cles-api) et [Authentification de l'API](/v1.0/reference-api/authentification-api).
