> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kori.ml/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification

> Échangez votre clé API et votre secret contre un token Bearer limité à des scopes.

L'API Marchand utilise un modèle d'identifiants en deux temps :

1. **Clé API + secret** — des identifiants de longue durée liés à votre compte marchand.
   Créés dans l'écran **Clés API** du tableau de bord. N'exposez jamais le secret dans du
   code côté client.
2. **Token Bearer** — un JWT de courte durée obtenu à partir de la clé et du secret. Il
   porte un ensemble de [scopes](/fr/scopes) et accompagne chaque appel à l'API.

## Obtenir un token

<ParamField header="X-API-Key" type="string" required>
  Votre clé API, par exemple `mk_...`.
</ParamField>

<ParamField header="X-API-Secret" type="string" required>
  Votre secret API, par exemple `ms_...`.
</ParamField>

```bash theme={null}
curl -X POST https://api.kori.ml/merchant/api/auth \
  -H "X-API-Key: mk_votre_cle_api" \
  -H "X-API-Secret: ms_votre_secret_api" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["pay", "balance"], "expires_in_hours": 24 }'
```

### Paramètres du corps

<ParamField body="scopes" type="string[]">
  Sous-ensemble des [scopes](/fr/scopes) de votre clé à inscrire dans le token. Par
  défaut `["pay", "deposit", "balance"]` si le champ est omis.
</ParamField>

<ParamField body="expires_in_hours" type="integer" default="24">
  Durée de vie du token en heures, entre `1` et `720` (30 jours).
</ParamField>

<Note>
  L'endpoint `/auth` est limité à **20 requêtes par tranche de 15 minutes**. Mettez le
  token en cache et réutilisez-le jusqu'à son expiration plutôt que de vous authentifier à
  chaque appel.
</Note>

## Utiliser le token

Envoyez-le comme token Bearer sur tous les autres endpoints :

```bash theme={null}
curl https://api.kori.ml/merchant/api/balance \
  -H "Authorization: Bearer <token>"
```

Si le token est absent ou invalide, vous recevez un `401`. S'il est valide mais qu'il lui
manque le scope exigé par l'endpoint, vous recevez un `403`, le message nommant le scope
requis.

## Liste blanche d'adresses IP

Si vous ajoutez des adresses IP à la liste blanche de votre compte (tableau de bord →
**Clés API → Liste blanche IP**), les requêtes venant de toute autre IP sont rejetées
avec un `403`, même avec un token valide. Laissez la liste vide pour autoriser toutes
les IP.

## Bonnes pratiques de sécurité

<AccordionGroup>
  <Accordion title="Gardez les secrets côté serveur" icon="lock">
    Le secret API et les tokens Bearer ne doivent jamais apparaître dans le code d'un
    navigateur ou d'une application mobile. Effectuez les appels depuis votre backend.
  </Accordion>

  <Accordion title="Accordez le minimum de privilèges" icon="shield-halved">
    N'accordez à une clé que les [scopes](/fr/scopes) dont elle a besoin, et demandez un
    ensemble encore plus restreint dans l'appel `/auth` lorsque c'est pertinent.
  </Accordion>

  <Accordion title="Renouvelez vos identifiants" icon="arrows-rotate">
    Vous pouvez régénérer vos identifiants API depuis le tableau de bord à tout moment.
    L'ancienne clé est alors immédiatement invalidée.
  </Accordion>
</AccordionGroup>