> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/keryo-docs-fr/developpeurs/authentication.md).

# Authentification

Créez des clés API scopées, comprenez la liste des scopes et authentifiez vos requêtes REST.

L'accès programmatique à l'API REST de Keryo s'authentifie à l'aide de **clés API**. Chaque clé est **scopée** — elle ne peut réaliser que les actions accordées par ses scopes. Cette page couvre la création et la gestion des clés, la liste complète des scopes, et la façon d'envoyer une clé dans une requête.

{% hint style="info" %}
Le connecteur MCP s'authentifie avec des **jetons d'accès OAuth 2.1** plutôt qu'avec des clés API. Si vous développez ou connectez un client IA, consultez [Connecteur MCP](/keryo-docs/keryo-docs-fr/developpeurs/mcp-connector.md).
{% endhint %}

## Gérer les clés API

Les clés API se gèrent via les endpoints `/api-keys`. La gestion des clés se fait **uniquement depuis l'application web / une session** : vous devez être connecté via une session cookie pour créer, lister, modifier ou supprimer des clés.

{% hint style="warning" %}
**Une clé ne peut pas gérer les clés.** Une clé API ne peut jamais créer ni révoquer d'autres clés — cela nécessite une session connectée. Cela limite l'impact d'une clé compromise.
{% endhint %}

| Méthode  | Chemin          | Description                                    |
| -------- | --------------- | ---------------------------------------------- |
| `GET`    | `/api-keys`     | Lister vos clés (aperçus masqués uniquement).  |
| `POST`   | `/api-keys`     | Créer une clé avec `{name, scopes}`.           |
| `PUT`    | `/api-keys/:id` | Modifier une clé (nom ou scopes, par exemple). |
| `DELETE` | `/api-keys/:id` | Supprimer (révoquer) une clé.                  |

### Créer une clé

Envoyez un nom et les scopes que la clé doit porter :

```json
{
  "name": "CI publisher",
  "scopes": ["posts:read", "posts:write", "posts:publish"]
}
```

La réponse contient la **valeur secrète de la clé une seule fois**, à la création. Conservez-la en lieu sûr : elle ne pourra plus être récupérée.

{% hint style="danger" %}
**Le secret n'est affiché qu'une seule fois.** Après la création, `GET /api-keys` ne renvoie qu'un **aperçu masqué** (jamais le secret complet). Si vous perdez une clé, supprimez-la et créez-en une nouvelle.
{% endhint %}

> *Les corps de réponse des endpoints `/api-keys` sont donnés à titre indicatif ; seuls la forme de requête `{name, scopes}` et le comportement « secret affiché une fois, masqué ensuite » sont spécifiés.*

## Scopes

Chaque clé API et chaque jeton OAuth 2.1 porte un ensemble de scopes. Voici la liste exacte :

| Scope           | Autorise                                                           |
| --------------- | ------------------------------------------------------------------ |
| `accounts:read` | Lire les espaces clients et leurs comptes sociaux connectés.       |
| `posts:read`    | Lister et lire les posts d'un espace.                              |
| `posts:write`   | Créer et modifier des brouillons de posts (y compris l'import).    |
| `posts:publish` | Publier des posts immédiatement, les planifier ou les replanifier. |
| `stats:read`    | Lire les statistiques par plateforme et les instantanés.           |

N'accordez à une clé que les scopes dont elle a besoin. Une requête vers un endpoint exigeant un scope que la clé ne possède pas est refusée avec un `403`.

{% hint style="info" %}
**Les sessions par cookie ne portent aucun scope.** Une session connectée à l'application web dispose d'un accès complet et n'est pas soumise aux vérifications de scope. Les scopes ne s'appliquent qu'aux clés API et aux jetons d'accès OAuth 2.1.
{% endhint %}

## Envoyer une clé

Envoyez la clé dans l'en-tête `Authorization` sous forme de jeton Bearer :

```bash
curl https://api.keryo.io/posts \
  -H "Authorization: Bearer <votre-cle-api>"
```

## Gating par offre

Posséder le bon scope est nécessaire mais pas toujours suffisant — certaines actions requièrent aussi une **offre** minimale :

* `POST /posts/import` (import de posts existants) requiert l'offre **Freelance** ou supérieure.
* Les endpoints `/statistics` requièrent l'offre **Studio** ou supérieure (en plus du scope `stats:read`).

Un jeton doté du bon scope mais d'une offre insuffisante est refusé avec un `403`. Voir [Limites de débit & erreurs](/keryo-docs/keryo-docs-fr/developpeurs/rate-limits-and-errors.md) pour la sémantique complète des erreurs.

## Pour aller plus loin

* [Référence de l'API](/keryo-docs/keryo-docs-fr/developpeurs/api-reference.md) — les endpoints débloqués par chaque scope.
* [Connecteur MCP](/keryo-docs/keryo-docs-fr/developpeurs/mcp-connector.md) — les jetons d'accès OAuth 2.1 pour les clients IA.