Authentification

La première étape de l'intégration avec l'API STACK consiste à comprendre le processus d'autorisation de l'API. Chaque fois qu'un partenaire fait une demande à l'API STACK , que ce soit au nom du partenaire ou au nom d'un utilisateur affilié à un partenaire, il doit être autorisé par le serveur d'autorisation de STACK.

OAuth 2.0 - Autorisation à deux pattes
OAuth 2.0 - Autorisation à trois pattes
Expiration du jeton

OAuth 2.0 - L'autorisation à deux jambes

L'autorisation bilatérale est utilisée lorsque votre intégration écrit des données dans un compte que vous contrôlez ou lit à partir de ce compte. Il s'agit typiquement d'une communication de serveur à serveur où vous pouvez créer des projets, des plans, des fichiers directement dans votre propre compte.

Obtention des justificatifs des clients

STACK fournira à un partenaire son propre identifiant et son secret client, qui constituent ensemble les informations d'identification de l'API. L'identifiant et le secret du client sont combinés, séparés par deux points et codés en base64 comme suit :

Combinez l'identifiant et le secret du client : ex. “5:11728663-C8DD-4B84-9B2B-4E3916631A54”
Assurez-vous que les champs "clientId:client-secret" sont encodés en Base64.

Ajouter les informations d'identification codées du client à l'en-tête d'autorisation de la demande :

Autorisation : Basic
NToxMTcyODY2My1DOERELTRCODQtOUIyQi00RTM5MTY2MzFBNTQ=

Obtention d'un jeton d'accès au nom du partenaire

To obtain an access_token, a Partner must make a POST request to this endpoint: “https://{server}/OAuth/Token” and include the Client Credentials in the Authorization header of the request. Replace {server} with the sandbox server URL provided along with your API credentials. A Grant Type is also required in the body of the request; “grant_type=client_credentials”.

Demande :

POST https://{server}/OAuth/Token
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Notez qu'il ne doit pas y avoir de fin de ligne après les données du formulaire, sinon un type de subvention non valide sera renvoyé. Cela inclut les retours de chariot (0x0d) et les caractères de retour à la ligne (0x0a).

Réponse :

{
“access_token”:
“tG05IRnPA3hBINzKmIU28zR60xqoachJzI5av5RMTeCRE8uNzeYt95w9XOmNon-4lF3KXQj
gakNfMT9nHgtRxItobmdkZ4xi849LlMhS6SKyCQvHI….”,
“token_type”: “Bearer”,
“expires_in”: 28799,
“refresh_token”:
“898c0a5d1a5c42a9898caf23de67467847db7c42e53f4aa8b599eadc495c55e4”
}

Notez le code d'accès (access_token) dans la réponse. L'access_token sera utilisé dans l'en-tête d'autorisation du porteur de toute demande future à l'API. Les access_tokens expireront comme indiqué dans le champ expires_in de la réponse et devront être rafraîchis à l'aide du refresh_token.

Détails du domaine :

Nom du champ	Type	Longueur	Objectif
jeton d'accès	chaîne de caractères	2048	L'access_token sera utilisé dans l'en-tête d'autorisation du porteur de toute demande future à l'API. Les access_tokens expireront comme indiqué dans le champ expires_in de la réponse et devront être rafraîchis à l'aide du refresh_token. La longueur du champ peut varier dans le temps et vous trouverez des chaînes d'environ 1030 octets, mais assurez-vous de réserver 2048 octets dans toute colonne de table dans laquelle vous le stockez.
type de jeton	chaîne de caractères		Toujours "Bearer", ce qui indique que c'est ainsi que vous devez utiliser ce jeton.
expires_in	int		Le nombre de secondes pendant lesquelles ce jeton est valide.
refresh_token	chaîne de caractères		Après expires_in seconds, ce refresh_token peut être utilisé dans un autre appel API pour récupérer un autre access_token.

Authentification des requêtes à l'API

Vous trouverez ci-dessous un exemple de POST pour créer un projet à l'aide de l'API de STACK:

En-têtes de requête :

POST https://{server}/api/v1/Projects HTTP/1.1
Authorization: Bearer 4M4tperlk1zmqEzPrfaFCLEn… (access_token)
…

Voir le document de référence de l'API pour plus de détails sur les demandes.

Actualisation des jetons d'accès

Comme indiqué ci-dessus, les access_tokens devront être actualisés. Le processus est similaire à l'obtention initiale d'un access_token. Utilisez vos identifiants client dans l'en-tête d'autorisation et formatez votre refresh_token comme indiqué dans l'exemple ci-dessous.

En-tête de la demande :

POST https:// {server}.net/OAuth/Token HTTP/1.1
Authorization: Basic (your Client Credentials)
Content-Type: application/x-www-form-urlencoded
refresh_token=d826c4204c847bf63a16d271adea23e…&grant_type=refresh_token

Réponse :

{
“access_token”:”qKDJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2dMAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”b368fd873df3406cb5b35482f68eb1597111ed851cf243df9edeb5e7e52ee4dc”
}

OAuth 2.0 - L'autorisation à trois pattes

L'autorisation à trois pattes est utilisée lorsque votre intégration écrit des données dans un compte ou lit des données à partir d'un compte au nom d'un utilisateur. L'utilisateur doit alors accorder à votre intégration la permission de contrôler ses données. Votre application demandera à contrôler le compte d'un utilisateur et celui-ci devra cliquer sur un bouton pour accorder à votre application les permissions appropriées.

Obtention de l'authentification au nom de l'utilisateur

Ce qui suit décrit comment autoriser l'accès à l'API au nom d'un utilisateur. L'idée est que l'un de vos clients interagit avec votre produit et que vous souhaitez le transférer sur STACK. Vous disposez déjà d'un jeton d'accès grâce au flux de travail à deux étapes ci-dessus, vous devez donc maintenant obtenir l'accès pour votre utilisateur.

Tout d'abord, l'utilisateur doit être redirigé vers la page d'autorisation de STACK. Cela peut être réalisé par une url de redirection appliquée à une action initiée par l'utilisateur, par exemple en cliquant sur un lien sur la page du partenaire pour visualiser un projet dans l'application STACK . La redirection contiendra le redirect_uri fourni par le partenaire et le ClientID fourni par STACK:

Demande :

https://{server}/OAuth/Authorize?client_id=(your
ClientId)&redirect_uri=(your redirect_uri
encoded)&state=partner-created-value&response_type=code

Le ClientID est l'identifiant que STACK vous a fourni pour votre Client Credentials.

Le redirect_uri est l'uri que vous avez fourni à STACK et qui est enregistré dans la base de données de STACKcomme faisant partie de vos informations de partenaire. Lorsqu'il est envoyé dans la chaîne de requête, l'uri doit être encodé.

Exemple :

http%3A%2F%2Fyour%2Fredirect_uri.com

Le paramètre d'état est généré par le partenaire pour l'usage du partenaire.

La partie response_type=code de la chaîne de requête indique au serveur d'autorisation STACK que vous demandez un code à usage unique (GUID généré par le serveur d'autorisation) à utiliser pour obtenir un access_token pour votre utilisateur.

Voici un exemple de ce que l'utilisateur verra généré par le serveur d'autorisation STACK .

Une fois que l'utilisateur a accordé l'accès au partenaire en cliquant sur le bouton "Accorder", il est redirigé vers le redirect_uri du partenaire et le code à usage unique est spécifié dans la chaîne de requête. La chaîne de requête renvoyée doit ressembler à l'exemple ci-dessous :

Exemple :

http://your/redirect_uri/?code=7d07711d50c14cfeb0759d262878b03b37c50b063
5614ee8893a166e526da90b&state=partner-created-value

Notez que le paramètre state renvoyé est la même valeur que celle transmise à STACK dans la requête originale. Le code fourni est de courte durée et configuré pour expirer dans 5 minutes. Si l'utilisateur choisit de cliquer sur le bouton Annuler, une redirection similaire se produira vers le Partner redirect_uri avec un argument de chaîne de requête d'erreur indiquant l'accès refusé.

http://your/redirect_uri/?error=access_denied&state=partners-unique-value

Le client s'attendrait à ce qu'on lui présente la même page partenaire que celle qu'il a utilisée pour lancer STACK. La demande d'obtention d'un code d'accès pour un utilisateur donné peut être faite à partir du serveur et ne nécessite aucune action supplémentaire de la part de l'utilisateur. La demande d'obtention d'un code d'accès pour l'utilisateur est similaire à la demande d'obtention d'un code d'accès pour un partenaire.

Demande :

POST https://{server}/OAuth/Token HTTP/1.1
Authorization: Basic
VEhJUyBJUyBCQVNFNjQgU1RSSU5HIE9GIFlPVVIgUEFSVE5FUklEfFBBUlRORVIgU0VDUkVU
Cg==
Content-Type: application/x-www-form-urlencoded
code=7d07711d50c14cfeb0759d262878b03b37c5&state=partner-created-value&re
direct_uri=(your redirect_uri)&grant_type=authorization_code

Réponse :

{
“access_token”:”dfsahjaAsdYza1Rp6VSYwJ5M7LPX-Do3aPCsaIrRzJ1_wsVt_6Whm2d
MAkeMYTs1S5uQe…..”,
“token_type”:”Bearer”,
“expires_in”:28799,
“refresh_token”:”jfdkshfjdhs73df3406cb5b35482f68eb1597111e
d851cf243df9e deb5e7e52ee4dc”
}

Expiration du jeton

Le code d'autorisation, le jeton d'accès et le jeton de rafraîchissement expirent tous à des moments différents. Le tableau ci-dessous explique les paramètres que vous devez gérer :

Type de jeton	Délai d'expiration	Raison
Code d'autorisation	5 minutes	Il s'agit d'une valeur éphémère, transmise au partenaire pour une utilisation immédiate afin de récupérer un jeton d'accès.
Jeton d'accès	8 heures	Un jeton d'accès, pour l'authentification à deux ou trois branches, représente uniquement une session connectée et est actualisé régulièrement pour s'assurer que l'état de la pièce d'identité n'a pas changé.
Jeton de rafraîchissement	90 jours	Cette longue période signifie que les autorisations accordées aux utilisateurs sont vérifiées à une fréquence constante.