Authentification
Chaque requête /v1 est authentifiée. Depuis vos propres systèmes,
authentifiez-vous avec un jeton d'accès personnel (PAT) envoyé comme jeton
bearer :
Authorization: Bearer waafir_pat_…Émettez, restreignez et révoquez les jetons sous Modules complémentaires → Configuration. Le guide des jetons d'accès personnels couvre l'émission, l'expiration (90 jours par défaut, 365 au maximum), l'affichage unique et la révocation. Ces règles sont les mêmes pour l'API de la plateforme. Cette page explique ce qu'un jeton permet de faire une fois que vous le détenez.
Un jeton d'accès personnel agit en tant que la personne qui l'a émis, au sein de l'organisation de cette personne. Il n'existe aucun paramètre d'organisation dans les URL ou les corps de requête, car le jeton la fixe déjà.
Les trois contrôles du jeton
Une requête authentifiée par jeton doit franchir ces trois contrôles, entre
autres. La politique de sécurité de l'organisation et les contrôles propres au
point de terminaison peuvent également la refuser (voir
ci-dessous). Deux des trois ont leur propre
code. Un refus lié au rôle peut renvoyer FORBIDDEN, que partagent d'autres
refus ; lisez donc le code en tenant compte des exigences du point de
terminaison.
| Contrôle | Question | Refus |
|---|---|---|
| Portée du jeton | La portée du jeton couvre-t-elle ce que fait ce point de terminaison ? | PAT_SCOPE_INSUFFICIENT 403 |
| Rôle | L'appelant détient-il le rôle qu'exige ce point de terminaison ? | FORBIDDEN 403, ou PAT_ROLE_CEILING 403 |
| Salle de données | Pour un jeton restreint à certaines salles de données, cette salle de données figure-t-elle sur sa liste ? | PAT_DATAROOM_SCOPE 403 |
Portées de jeton
Un jeton porte une seule portée : read, write ou admin, par ordre
croissant d'autorité. Une portée supérieure inclut tout ce qui se trouve en
dessous.
La portée requise par un point de terminaison découle par défaut de sa méthode HTTP :
GET,HEADetOPTIONSexigentread.- Toutes les autres méthodes (
POST,PATCH,PUT,DELETE) exigentwrite.
Certains points de terminaison déclarent une portée différente. Le cas habituel
est un POST qui ne fait qu'exécuter une requête et n'exige que read. La
référence des points de terminaison indique la
portée réellement exigée par chaque point de terminaison ; vérifiez-la donc à
cet endroit plutôt que de la déduire de la méthode.
Rôle requis et plafond de rôle
La portée indique ce que le jeton peut faire. Le rôle requis du point de
terminaison indique qui la personne doit être. De nombreux points de
terminaison /v1 exigent l'équipe de transaction (un propriétaire,
administrateur ou membre de l'organisation). Les modifications de l'équipe et
des autorisations d'accès, entre autres, exigent un propriétaire ou un
administrateur. Les investisseurs et autres invités ne détiennent aucun rôle
d'équipe de transaction ; les points de terminaison réservés à l'équipe de
transaction les refusent donc. D'autres points de terminaison ne déclarent
aucune restriction de rôle au niveau de la couche d'authentification et
vérifient l'accès à l'intérieur du point de terminaison. Par exemple, les routes
de suivi de portefeuille vérifient le module complémentaire Monitoring et
l'accès de l'appelant à Monitoring. La référence des points de
terminaison indique la restriction de rôle de
chaque point de terminaison. Lorsqu'aucune n'est déclarée, attendez-vous à ce
que le point de terminaison puisse tout de même refuser.
Un jeton enregistre également le rôle de son émetteur au moment de son émission, comme plafond. Le rôle que Waafir applique est le plus bas entre le
rôle actuel de l'émetteur et ce plafond. Un membre promu plus tard
administrateur agit toujours en tant que membre via un jeton émis auparavant ;
émettez un nouveau jeton pour utiliser le nouveau rôle. Une personne dont le
rôle est abaissé perd immédiatement l'autorité correspondante, quel que soit le
rôle enregistré par le jeton. Dans les deux cas, le refus est un 403, sous la
forme FORBIDDEN ou PAT_ROLE_CEILING.
Jetons restreints à certaines salles de données
Un jeton émis avec des salles de données précises sélectionnées, plutôt que Toutes les salles de données, n'atteint que ces salles. Une requête qui désigne une
autre salle de données est refusée avec PAT_DATAROOM_SCOPE. Certains points de
terminaison couvrant toute l'organisation refusent d'emblée un jeton restreint,
avec le même code, car leur réponse englobe des salles de données que le jeton ne peut
pas voir. Utilisez un jeton non restreint pour ceux-ci.
GET /api/v1/session accepte les deux types.
Autres refus que vous pouvez rencontrer
401 UNAUTHORIZED: pas d'en-têteAuthorization, ou un jeton inconnu, expiré ou révoqué.404pour la ressource d'une autre organisation. Un identifiant appartenant à une autre organisation est traité comme introuvable ; son existence n'est donc pas confirmée.- Aucune dérogation propriétaire/administrateur sur les fichiers restreints. Dans l'application, un propriétaire ou un administrateur de
l'organisation voit chaque fichier restreint. Un jeton, non : il n'atteint un
fichier restreint que si son propriétaire l'a créé ou détient une autorisation
sur celui-ci. Une requête désignant un fichier qu'il ne peut pas lire reçoit
la même réponse qu'un fichier inexistant (pour
/api/v1/grants, un400désignant le fichier, ou un404pour l'autorisation), avec un message indiquant qu'il est « not found, or not readable by this credential », de sorte que la réponse ne confirme jamais l'existence du fichier. - Politique de sécurité de l'organisation. Si votre organisation dispose
d'une liste d'adresses IP autorisées, une requête provenant de l'extérieur
reçoit
IP_BLOCKED. L'application obligatoire de l'authentification à deux facteurs peut renvoyerMFA_SETUP_REQUIREDouMFA_CHALLENGE_REQUIRED. 429 RATE_LIMITED. Certains points de terminaison déclarent un plafond par minute pour chaque identité, indiqué sur le point de terminaison. Les autres utilisent la valeur par défaut de la plateforme. Patientez puis réessayez.
La page des codes d'erreur liste les codes connus avec leur signification.