S'authentifier auprès de l'API
01En une phrase #sec_36fbfa52
L'API REVIEWIT n'accepte qu'un seul mode d'authentification — OAuth 2.0 client credentials — et ne connaît que des machines : il n'existe aucune façon d'appeler l'API au nom d'une personne.
02Une identité de machine, jamais un utilisateur #sec_ca4b0dd0
C'est un choix, pas une limitation à contourner. Une décision de recertification tire toute sa valeur de son imputabilité à une personne qui a regardé, jugé, et qui en répond. Une identité de machine ne peut pas porter ce genre de décision — donc l'API ne l'autorise pas, et son mode d'authentification le rend impossible plutôt que déconseillé.
Concrètement : le seul flux autorisé est client_credentials . Les flux qui supposent un utilisateur devant un navigateur — code d'autorisation, mot de passe, implicite — ne sont pas activés. Un client qui les tente reçoit un refus du serveur de jetons, pas une page de connexion.
03Obtenir un jeton #sec_02b8bbd6
Le point d'appel est POST /connect/token . Il attend les paramètres standard du flux client credentials , en application/x-www-form-urlencoded .
POST /connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=VOTRE_CLIENT_ID
&client_secret=VOTRE_SECRET
&scope=campaigns.read reviews.readLa réponse porte un jeton d'accès et sa durée de vie.
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600
}Le jeton se présente ensuite sur chaque appel, dans l'en-tête Authorization .
Authorization: Bearer eyJhbGciOi...04Ce que dure un jeton #sec_4d63dc43
Soixante minutes par défaut. La valeur est un réglage de déploiement ( Api:AccessTokenMinutes ) : votre installation peut l'avoir raccourcie, jamais rallongée sans que l'éditeur le sache.
Ne demandez pas un jeton par appel. Le point d'appel de jetons a sa propre limite de débit, plus basse que celle des points d'appel de données : soixante par minute. Un client qui redemande un jeton à chaque requête épuise ce plafond bien avant celui des données, et se retrouve bloqué sur l'authentification alors que son quota de lecture est intact. Conservez le jeton et renouvelez-le à l'approche de son échéance.
05Le jeton est signé, il n'est pas chiffré #sec_fb3f6e49
Le jeton est un JWT signé par un certificat. Il est lisible : n'importe qui le tenant peut en lire le contenu — l'identifiant du client, les portées accordées, l'échéance.
C'est délibéré. La confidentialité du transport est assurée par TLS ; le chiffrement du jeton n'ajouterait rien contre un attaquant qui le détient déjà, et rendrait illisibles les outils de diagnostic qui aident à comprendre un refus. En revanche, un jeton qui fuite est un jeton utilisable : il se traite comme un secret jusqu'à son échéance.
06Les portées #sec_682200d2
Une portée est un droit de lecture ou d'écriture sur un domaine. Le jeton n'en porte que ce que vous demandez, et le client n'obtient que ce qui lui a été accordé à l'enregistrement : demander plus ne donne pas plus.
| Portée | Ce qu'elle ouvre |
|---|---|
| campaigns.read | Les campagnes de recertification |
| reviews.read | Les revues et leurs décisions |
| evidence.read | Les preuves signées |
| resources.read | Les ressources examinées |
| audit.read | La piste d'audit |
| deletions.read | Les demandes de suppression |
| webhooks.manage | Les abonnements aux événements |
Quatre portées existent sans qu'aucun point d'appel ne les exige encore : campaigns.manage , delegations.manage , collect.trigger et deletions.manage . Elles sont déclarées parce que le serveur de jetons les connaît, et un client peut les demander ; elles n'ouvrent aujourd'hui aucune écriture, parce que les points d'appel correspondants n'existent pas encore. Les demander ne casse rien et ne sert à rien.
07Demandez le moins possible #sec_00fcfeab
Une portée accordée reste accordée. Demandez celles dont l'intégration a besoin, pas celles dont elle pourrait avoir besoin un jour : le jour venu, une portée s'ajoute en une ligne, tandis qu'un jeton qui fuite emporte tout ce qu'il portait.
08Vérifier ce que porte un jeton #sec_b38a4efa
Deux points d'appel de diagnostic répondent à la question sans qu'il faille décoder le jeton à la main.
GET /api/v1/diagnostics/whoami dit quel client vous êtes et quelles portées vous portez. GET /api/v1/diagnostics/scope-probe dit si une portée donnée passe la porte.
Ils servent à comprendre un refus. Un 403 sur un appel de données se diagnostique en trois secondes avec le premier, et en trois heures sans lui.
09À retenir #sec_082cfbe9
Un mode d'authentification, celui des machines. Un jeton d'une heure, conservé et réutilisé. Des portées demandées au plus juste. Et deux points d'appel de diagnostic qui répondent avant qu'on ouvre un ticket.