Catalogue de scopes — API publique Pesia
Convention
Les scopes Pesia sont des chaînes plates au format <resource>:<action>.
Il n'existe pas de hiérarchie : salary:read ne donne pas accès à org:read.
Chaque scope doit être déclaré explicitement dans le grant.
Pour demander un token incluant un scope métier, combinez les deux chaînes techniques et le scope :
--data-urlencode 'scope=urn:zitadel:iam:org:project:id:<projectId>:aud urn:zitadel:iam:user:resourceowner salary:read'
Les deux chaînes techniques sont obligatoires toutes les deux. S'il en manque
une, le serveur d'autorisation délivre quand même un token, mais l'API répond
401. Voir Authentification pour le détail.
Scopes actifs
Ces 6 scopes sont disponibles en production :
| Scope | Ressource | Endpoints | Statut |
|---|---|---|---|
salary:read | SMIC, grilles légales | GET /partner/v1/smic* | Actif — v1.1 |
org:read | Organisation appelante | GET /partner/v1/organizations/me | Actif — v1.1 |
agency:read | Agences de l'organisation | GET /partner/v1/agencies | Actif — v1.1 |
webhooks:manage | Subscriptions webhooks | GET/POST/PATCH/DELETE /partner/v1/webhooks/subscriptions | Actif — v1.1 |
payroll:simulate | Soumission d'un lot de paie, codes PCS-ESE acceptés | POST/GET /partner/v1/payroll-batches*, GET /partner/v1/pcs-ese-codes | Actif |
dpae:write | Déclarations préalables à l'embauche | POST/GET /partner/v1/dpae/submissions* | Actif |
Scopes différés (documentés — inactifs)
Ces 7 scopes seront proposés dans une version ultérieure. Ils sont listés ici
pour vous permettre d'anticiper vos intégrations. Ils ne sont pas encore
disponibles et retournent 403 insufficient_scope s'ils sont demandés.
| Scope | Ressource | Disponibilité |
|---|---|---|
conventions:read | Conventions collectives (séparé de salary:read) | Version ultérieure |
employees:read | Salariés intérimaires (lecture) | Version ultérieure |
employees:write | Salariés intérimaires (écriture) | Version ultérieure |
contracts:read | Contrats et missions (lecture) | Version ultérieure |
contracts:write | Contrats et missions (écriture) | Version ultérieure |
payroll:read | Bulletins de paie (lecture) | Version ultérieure |
dsn:read | Déclarations DSN | Version ultérieure |
Les scopes différés seront ajoutés de façon additive — ils n'introduiront aucun breaking change pour les intégrations existantes (voir Stabilité du contrat).
Politique de scopes
- Principe du moindre privilège : ne demandez que les scopes que votre intégration utilise réellement.
- Pas de scope par défaut : un grant sans scopes accordés ne peut accéder à aucun endpoint protégé.
- Modification de scopes : pour ajouter ou retirer un scope d'un grant existant, contactez votre interlocuteur Pesia. Une rotation de secret n'est pas nécessaire.
Erreur insufficient_scope
Si vous appelez un endpoint dont le scope requis n'est pas dans votre grant :
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"type": "https://docs.pesia.fr/partner/errors/insufficient_scope",
"title": "Insufficient Scope",
"status": 403,
"detail": "An error occurred.",
"code": "insufficient_scope",
"missing": ["salary:read"],
"instance": "/partner/v1/smic",
"timestamp": "2026-08-10T12:00:00.000Z"
}
Le tableau missing liste tous les scopes manquants (sémantique AND — tous les scopes requis
doivent être présents).
Voir aussi
- Authentification
- Webhooks — scope
webhooks:manage - DPAE — scope
dpae:write