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

# Authentification

> Signez l'échange HMAC-SHA256 et utilisez le bearer renvoyé par MARKO.

L'API utilise deux éléments distincts : une **clé API** avec un identifiant public `key_id` et un secret, puis un **bearer de courte durée** pour les routes métier. Le secret sert uniquement à signer `POST /v1/auth/token` ; il ne doit pas être transmis aux routes métier ni utilisé dans un navigateur.

## Signature de l'échange

Construisez les quatre lignes suivantes avec des sauts de ligne `\n`, sans saut de ligne final :

```text theme={null}
MARKO-EXTERNAL-API-TOKEN-V1
{key_id}
{timestamp}
{nonce}
```

`timestamp` est l'heure Unix en secondes. Générez un `nonce` différent pour chaque échange. Calculez la signature HMAC-SHA256 de ce message avec le secret API et encodez-la en hexadécimal. Envoyez ensuite :

```http theme={null}
POST /v1/auth/token HTTP/1.1
Content-Type: application/json

{"key_id":"YOUR_PUBLIC_KEY_ID","timestamp":1760000000,"nonce":"UNIQUE_NONCE","signature":"HEX_HMAC_SHA256"}
```

La réponse inclut `access_token`, `expires_in`, `expires_at` et `environment`. Renouvelez le bearer après son expiration en créant un nouvel échange signé. Pour les autres routes, utilisez :

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Une clé peut être limitée par scopes, routes et adresses IP. Le scope nécessaire figure dans le texte de chaque page API et dans `x-marko-required-scope` de l'[OpenAPI enrichi](https://raw.githubusercontent.com/mathieuworoniecki/marko-developer-docs/main/openapi.json). L'administrateur de l'entité peut exporter une version du contrat filtrée selon une clé donnée. Les routes déléguées exigent aussi les [capacités et headers correspondants](/scopes-and-delegation).

## Contraintes de l'échange

`key_id` contient 4 à 24 lettres minuscules ou chiffres. Utilisez l'identifiant réel de la clé; les marqueurs `YOUR_PUBLIC_KEY_ID` des exemples doivent être remplacés. `nonce` contient 16 à 128 lettres ASCII, chiffres, `_` ou `-`. La signature contient exactement 64 caractères hexadécimaux et `timestamp` est un entier positif ou nul.

Synchronisez l'horloge de votre serveur. La fenêtre d'horloge et la durée du bearer sont configurables; utilisez `expires_in` et `expires_at` retournés plutôt qu'une durée codée en dur. Évitez de refaire un échange pour chaque appel : réutilisez le bearer jusqu'à son renouvellement, en coordonnant ce renouvellement si plusieurs workers partagent la clé.

Après un `401`, vérifiez d'abord que le bearer vient du même hôte et contexte, puis refaites au besoin un échange avec un **nouveau nonce**. Ne renvoyez pas aveuglément le payload signé d'un échange déjà consommé. Pour une écriture métier, le renouvellement du bearer ne change ni son intention ni sa clé d'idempotence.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.