Introduction

Authentification

Deux acteurs, deux mécanismes : le vérificateur s’authentifie par clé API, le détenteur par signature de son portefeuille.

Les routes d’authentification sont publiques mais strictement limitées en débit (10 requêtes par minute) pour prévenir le bruteforce. Les réponses n’indiquent jamais si un identifiant existe : message générique et code 401uniforme en cas d’échec.

Vérificateur : jeton par clé API

Échangez votre clé API contre un jeton d’accès (JWT portant le rôle verifier). Le jeton est ensuite envoyé dans l’en-tête Authorization: Bearer sur les routes protégées. Le SDK gère automatiquement cet échange et le renouvellement sur 401.

POST/auth/verifier/tokenpublic (limité)

Champ	Type	Description
`apiKey`requis	string (min. 8)	Clé API secrète du vérificateur, émise depuis la console.

1curl -X POST https://api.ayiid.example/auth/verifier/token \
2  -H "content-type: application/json" \
3  -d '{ "apiKey": "sk_live_..." }'

Réponse (HTTP 201) :

1{
2  "accessToken": "eyJhbGci...",
3  "message": "Jeton emis."
4}

Gardez la clé côté serveur

La clé API accorde l’accès au compte vérificateur. Ne l’exposez jamais dans un client web ou mobile : appelez toujours l’API depuis votre backend.

Détenteur : login par signature

Un détenteur (rôle holder) s’authentifie en prouvant qu’il contrôle le portefeuille lié à son identité. Le flux se fait en deux temps : demande d’un défi (nonce), puis renvoi de la signature du nonce.

Demander un défi

POST/auth/holder/challengepublic (limité)

Champ	Type	Description
`did`requis	string	DID du détenteur.

1curl -X POST https://api.ayiid.example/auth/holder/challenge \
2  -H "content-type: application/json" \
3  -d '{ "did": "did:ayi:z6Mkf...abcd" }'

Vérifier le défi

Le portefeuille signe le nonce reçu ; la vérification renvoie une paire de jetons (accès + rafraîchissement).

POST/auth/holder/verifypublic (limité)

Champ	Type	Description
`did`requis	string	DID du détenteur.
`signature`requis	string	Signature du nonce par le portefeuille du détenteur.

Rotation du jeton de rafraîchissement

POST/auth/refreshpublic (limité)

Champ	Type	Description
`refreshToken`requis	string	Jeton de rafraîchissement obtenu au login.

1curl -X POST https://api.ayiid.example/auth/refresh \
2  -H "content-type: application/json" \
3  -d '{ "refreshToken": "rt_..." }'

Rôles et portée

Les jetons portent un rôle (verifier, holder, admin) et un environnement (SANDBOX ou PRODUCTION). Les routes protégées vérifient le rôle ; pour un détenteur, l’identité concernée est toujours déduite du jeton, jamais du corps de la requête.