Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

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ôleQuestionRefus
Portée du jetonLa portée du jeton couvre-t-elle ce que fait ce point de terminaison ?PAT_SCOPE_INSUFFICIENT 403
RôleL'appelant détient-il le rôle qu'exige ce point de terminaison ?FORBIDDEN 403, ou PAT_ROLE_CEILING 403
Salle de donnéesPour 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, HEAD et OPTIONS exigent read.
  • Toutes les autres méthodes (POST, PATCH, PUT, DELETE) exigent write.

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ête Authorization, ou un jeton inconnu, expiré ou révoqué.
  • 404 pour 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, un 400 désignant le fichier, ou un 404 pour 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 renvoyer MFA_SETUP_REQUIRED ou MFA_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.