Authentification et appel endpoint
- 04 Nov 2024
- 3 Minutes à lire
- Impression
- SombreLumière
- PDF
Authentification et appel endpoint
- Mis à jour le 04 Nov 2024
- 3 Minutes à lire
- Impression
- SombreLumière
- PDF
Résumé de l’article
Avez-vous trouvé ce résumé utile ?
Merci pour vos commentaires
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.
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
Ce token est d'une validité de 60 minutes et peut être utilisé et réutilisé pour tous les appels réalisés durant cette période. Pour des raisons de performance, il convient de rationaliser au maximum vos demandes de jeton, l'idéal étant d'attendre que votre token expire (ou soit sur le point d'expirer) pour en demander un nouveau.
Rate limiting sur l'authentification
Les demandes intempestives de token (ex : une demande de jeton par appel API) peuvent avoir des conséquences sur les performances des API, voire de l'application My Silae dans son ensemble.
Pour prévenir les mauvaises pratiques et garantir un service optimal pour tous, une limite d’authentification à 60 tokens / minute est mise en place à partir du mardi 10/12/24 (et dès le 05/11 /24 sur l'environnement de test).
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 ?