Scopes

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

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.

Le catalogue

L’ensemble des scopes attribuables est fermé et livré avec le contrat. Le voici en entier — une ligne par ressource, chacune avec son scope .read et .write :

Scopes	Couvre
account.read · account.write	Réglages du tenant (singleton).
areas.read · areas.write	Zones à l’intérieur d’un site.
availability.read · availability.write	Blocs de disponibilité des collaborateurs (récurrents compris).
break_rules.read · break_rules.write	Définitions des règles de pause.
budgets.read · budgets.write	Budgets de personnel et objectifs de chiffre d’affaires.
employees.read · employees.write	Collaborateurs, leurs affiliations, invitations et cycle de vie.
employment_types.read · employment_types.write	Types de contrat et leurs valeurs de paie par défaut.
events.read · events.write	Événements généraux (hors shift) et leurs participants.
holidays.read · holidays.write	Calendrier des jours fériés.
labor_cost.read	Rapport sur le coût du travail.
leave_balances.read	Soldes d’absence (lecture seule).
leave_policies.read · leave_policies.write	Politiques d’absence et leurs paliers.
leave_requests.read · leave_requests.write	Demandes d’absence et leurs transitions d’examen.
locations.read · locations.write	Sites.
open_shifts.read	Offres de shifts ouverts (lecture seule sur cette API).
positions.read · positions.write	Postes, les compétences qu’ils exigent et les assignations de collaborateurs.
shifts.read · shifts.write	Shifts, leur état de publication et leurs assignations.
skills.read · skills.write	Catalogue de compétences.
swaps.read	Offres d’échange de shifts (lecture seule sur cette API).
time_compensation.read · time_compensation.write	Grand livre et soldes de bonification en temps.
timesheets.read · timesheets.write	Rapports d’heures, timbrages, pauses et approbations.
webhook_endpoints.read · webhook_endpoints.write	Enregistrement des points de terminaison de webhook et rotation du secret.
webhook_log.read	Historique des événements distribués, pour la réconciliation.
work_rules.read · work_rules.write	Règles de travail (y compris le bloc de bonification en temps selon l’art. 17b).

Pour un seul point de terminaison, tu n’as pas besoin de ce tableau : 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 et le tableau ci-dessus dérivent tous deux 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 à support@shiftavo.com — 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.