Authentification

L'API Staff & Go est un serveur de ressources OAuth 2.0. Votre application s'authentifie pour elle-même avec le flux client credentials — pas de connexion d'utilisateur final, pas de redirection, pas de refresh token.

Obtenir un jeton

Les identifiants sont délivrés par environnement par Staff & Go. Échangez-les auprès du serveur d'autorisation :

curl -X POST "https://<hote-serveur-autorisation>/realms/staffngo-partners/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

Envoyez le jeton à chaque appel :

Authorization: Bearer <access_token>

Émettez un nouveau jeton peu avant l'expiration du précédent. Un jeton coûte peu ; une rafale de réessais déclenchée par des expirations simultanées coûte cher, et elle est décomptée de votre quota.

Scopes

Chaque endpoint déclare les scopes qu'il exige ; la référence les liste opération par opération.

Scope	Autorise
`external-api`	Accès de base à l'API.
`partner:read`	Lire votre propre profil partenaire.
`leaves:read`	Lire les données de congés.
`leaves:write`	Créer ou modifier des données de congés.
`payroll:read`	Lire les données de paie.
`payroll:trigger`	Déclencher une distribution de paie.
`referentials:read`	Lire les référentiels, ceux de la plateforme comme ceux de la société — voir Découverte.
`audit-entries:read`	Relire votre propre journal d'audit — voir Journal d'audit.
`beta:access`	Appeler les endpoints marqués `Beta` — aucun aujourd'hui, voir Cycle de vie.

N'ajoutez pas de paramètre scope à la demande de jeton. Les scopes accordés à votre application sont rattachés à vos identifiants et entrent dans le jeton sans être réclamés.

Les nommer est même risqué : le serveur d'autorisation refuse la demande entière dès qu'un scope nommé ne vous est plus accordé — invalid_scope, aucun jeton, et un message qui énumère tous les scopes demandés plutôt que celui qui a disparu.

⚠️ C'est dans la référence d'API de ce site que le piège se referme le plus souvent. Son panneau « Authorize » construit sa liste de scopes depuis le contrat publié, qui nomme tous ceux que cette API connaît — y compris les sous-scopes de champ (employments:read:compensation, leaves:read:reason, payroll:read:amounts). Ils y figurent pour que vous puissiez découvrir ce qui libère un champ, pas parce que vous les détenez : un sous-scope n'est accordé que sur besoin exprimé, et leaves:read:reason porte des données de santé au sens de l'article 9. Tout cocher ne vous donne aucun jeton. Laissez la sélection vide, ou ne cochez que ce que vous savez vous avoir été accordé.

Un jeton auquel il manque un scope exigé reçoit un 403 avec type = scopes/insufficient, et le detail nomme le scope manquant.

Après toute modification de vos accès, demandez un nouveau jeton. Quand l'administrateur de l'entreprise cliente retire un accès, les jetons déjà émis sont désavoués : ils reçoivent un 401, pas un 403, parce qu'ils ont été signés sous une habilitation qui n'est plus la vôtre. Attendre ne les rétablit pas, et un accès rendu ensuite ne les ressuscite pas non plus — seul un jeton frappé après le changement porte vos droits du moment. Si vos appels passent en 401 sans explication, c'est la première chose à faire.

Vérifier ce que porte votre jeton

GET /api/v1/client/partner/profile renvoie l'identité résolue par l'API : votre identifiant partenaire, le tenant client sur lequel vos appels agissent, et les scopes réellement présents sur le jeton. C'est le moyen le plus rapide de diagnostiquer un 403. La version 2 de cet endpoint ajoute le plan, le demandeur et l'état des modules — voir Découverte.

Jetons legacy — dépréciés

Les intégrations antérieures à OAuth émettent un jeton BearerClient depuis /api/v1/token. Il fonctionne toujours, et il est déprécié : une nouvelle intégration ne doit pas l'utiliser.

Il n'est pas seulement plus ancien — il se comporte différemment, sur des points qui ne seront pas repris :

il est exempté du quota, donc il ne renvoie aucun en-tête RateLimit ni aucun signal de saturation ;
il est exempté de l'idempotence, donc une écriture rejouée n'est pas dédoublonnée ;
il ne peut porter aucun scope, donc tout endpoint qui en exige un le refuse avec 403.

Pour migrer, demandez des identifiants partenaire à Staff & Go, remplacez l'obtention du jeton par l'appel client credentials ci-dessus, et laissez le reste de votre intégration inchangé — les endpoints et leurs contrats sont identiques.

Protéger le secret

Le client secret authentifie votre application à lui seul. Gardez-le côté serveur, hors des navigateurs, des applications mobiles, des dépôts et des logs. En cas de fuite, demandez sa rotation à Staff & Go — une rotation invalide immédiatement l'ancien.