Authentification et appel endpoint
- 23 Oct 2023
- 3 Minutes à lire
- Impression
- SombreLumière
- PDF
Authentification et appel endpoint
- Mis à jour le 23 Oct 2023
- 3 Minutes à lire
- Impression
- SombreLumière
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
Le système d'authentification des API REST Silae Paie se base sur le standard OAuth2 (client-credential).
La séquence de connexion se déroule de cette manière :
1. Requête d'authentification
Envoi de la requête d'authentification via l'url https://payroll-api-auth.silae.fr/oauth2/v2.0/token.
Les paramètres suivants doivents être passés dans une requête de type POST au format "url encoded" (Content-Type : "application/x-www-form-urlencoded" dans les headers de la requête) :
| Clé | Valeur |
|---|---|
| grant_type | client_credentials |
| client_id | ClientID de votre compte API. Cette information est disponible dans l'écran d'informations générales du Portail API |
| client_secret | ClientSecret correspondant au ClientID. Cette information peut être récupérée lors de la génération du ClientSecret via le Portail API |
| scope | https://silaecloudb2c.onmicrosoft.com/36658aca-9556-41b7-9e48-77e90b006f34/.default |
Le corps du message HTTP envoyé est une "query string". Les paires nom/valeur sont séparées par l'esperluette (&) et les noms sont séparés des valeurs par le symbole égal (=). Exemple :
grant_type=client_credentials&client_id=votre-client-id&client_secret=votre-client-secret&scope=le-scope-de-l-authentification
Les caractères non alphanumériques contenus dans les valeurs doivent être remplacés par "%HH", un pourcentage et deux chiffres hexadécimaux représentant le code ASCII du caractère. Vous pouvez vous référer à la recommandation du w3c pour plus de précisions.
2. Réponse - Authentification
Si l'authentification est réussie, la réponse contiendra un access_token qui sera indispensable pour utiliser les APIs.
Utilisation de l'access token
Lors de la création de l'access token, La réponse renvoyée contient les éléments suivants :
- not_before : la date de début de validité exprimée en Unix time
- expires_in : la durée de vie exprimée en seconde
- expires_on : la date d'expiration exprimée en Unix time
Vous devez absolument utiliser le même token pour tous les appels à l'API. Ce token est valide jusqu'à sa date d'expiration. Une fois le token expiré, vous pouvez en créer un nouveau. Vous pouvez aussi en créer un nouveau juste avant la date d’expiration.
Au cas où vous créeriez un trop grand nombre de token nous pourrions vous interdire d'en créer plus d'un seul par heure.
Si l'authentification échoue, un message d'erreur est renvoyé avec 2 paramètres (error et error_description) détaillant l'erreur rencontrée.
Exemples d'erreurs :
| error | error_description | Source de l'erreur |
|---|---|---|
| unsupported_grant_type | ...The supplied grant_type [client_credential] is not supported... | le paramètre grant_type doit valoir client_credentials pour que l'authentification fonctionne |
| invalid_client | ...The client id 'XXXXXXX' specified in the request is not registered... | Le paramètre client_id ne correspond pas à un compte API existant |
| invalid_client | ...The specified client_secret does not match the expected value for this client.... | Le paramètre client_secret ne correspond pas au paramètre client_id renseigné |
| invalid_grant | ...The service has encountered an internal error. Please reauthenticate and try again...... | Il est possible que le paramètre scope soit mal renseigné, assurez-vous de bien renseigner la valeur indiquée dans le paragraphe 1. Requête d'authentification |
3. Appel endpoint API REST
L'utilisation des API REST Silae Paie se fait ensuite de la même manière pour tous les appels, en appelant l'url https://payroll-api.silae.fr/payroll et en passant les headers HTTP suivants :
| Clé | Valeur | Commentaire |
|---|---|---|
| Authorization | Valeur de l'access_token reçu en réponse à l'authentification précédée de 'Bearer ' | Authorization de type Bearer. |
| Ocp-Apim-Subscription-Key | Clé de la configuration d'accès API | Cette information peut être récupérée lors de la génération de la clé liée à la configuration d'accès API correspondante via le Portail API |
| dossiers | Numéro du dossier | Ce header doit contenir le numéro du dossier concerné par la requête. Si la requête en concerne pas un dossier particulier (par exemple pour le endpoint ListeDossier), ce header doit malgré tout être présent, mais vide. |
Note sur la subscription key (clé principale - secondaire)
C'est à partir de la subscription key que sont gérées les autorisations. Cela signifie que c'est via le paramètre Ocp-Apim-Subscription-Key que l'on indique quelle configuration d'accès API est utilisée, et donc à quel(s) dossier(s) on va pouvoir accéder.
Les subscription-key (Ocp-Apim-Subscription-Key) sont générées dans le portail API, à partir du menu d'action à droite de la configuration d'accès API concernée :
Les configurations d'accès API sont créées par le partenaire directement depuis Silae.
4. Réponse
Réponse à la requête envoyée, suite au traitement.
Note sur la plage horaire des appels
Nos plateformes sont actualisées tous les jours entre 1h et 5h. il est vivement conseillé de ne pas générer d'appel sur ce créneau horaire au risque de rencontrer des erreurs.
Cet article vous a-t-il été utile ?