Scopes

Chaque opération requiert exactement un scope, nommé <resource>.<action>, par exemple :

shifts.read        locations.write        timesheets.read

• GET exige .read.

• POST, PATCH, DELETE exigent .write.

• L’écriture implique la lecture — shifts.write satisfait aussi shifts.read, tu n’as donc jamais besoin de demander les deux.

Chaque opération de la référence de l’API déclare le scope exact qu’elle exige, directement sur l’opération. Cette exigence dérive de la même valeur que lit le contrôle d’autorisation du serveur ; ce qui est documenté et ce qui est appliqué ne peuvent donc pas diverger.

Demander les bons

Les scopes sont accordés par client d’intégration au moment où nous l’enregistrons ; demande donc ce que l’intégration fait réellement, et rien de plus. Un export de paie qui lit les heures obtient timesheets.read et rien d’autre.

Une faute de frappe est détectée à l’enregistrement, pas à l’exécution : shift.read est refusé avec une suggestion, plutôt que d’enregistrer un client qui échouerait à chaque appel.

Pour ajouter un scope plus tard, écris à l’assistance — cela ne nécessite pas de nouveaux identifiants.

Quand un scope manque

Un appel avec un jeton valide mais sans l’autorisation requise donne :

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "…",
    "details": []
  }
}

un statut 403. C’est distinct d’un 401 (le jeton lui-même est mauvais — voir Authentification) et d’un 404, qui est aussi ce que tu obtiens pour un enregistrement hors de ton entreprise, afin que son existence ne fuite jamais.