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 :
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 :
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 :
x-marko-required-scope de l’OpenAPI enrichi. 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.
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.