Guide d’authentification

La première étape consiste à demander l’autorisation de l’utilisateur de votre application. Vous redirigerez l'utilisateur vers le point de terminaison d'autorisation où il lui sera demandé de se connecter avec ses informations d'identification Studio et d'accorder l'autorisation à votre application. Pour ce faire, effectuez une requête GET au point de terminaison d’autorisation avec les paramètres suivants.

Point de terminaison d'autorisation

https://api.bluebeam.com/oauth2/authorize

Paramètres de la requête

Les paramètres doivent être passés dans une chaîne de requête.

Portées pour les points de terminaison de Studio

Rafraîchir les jetons
Assurez-vous de demander la portée « offline_access » dans votre demande pour recevoir un refresh_token en retour. Pour en savoir plus sur les refresh_tokens, voir l’étape 4 ci-dessous.

Exemple de demande

GET https://api.bluebeam.com/oauth2/authorize?response_type=code&client_id=b5f9fc7c-60dd-469f-a21e-3f4a7ceb874b&redirect_uri=http://myserver.com&scope=full_prime offline_access jobs&state=myteststate

Expérience utilisateur

Les utilisateurs seront dirigés vers la page de connexion Bluebeam.

Une fois connecté, l'utilisateur peut sélectionner Autoriser l'accès pour accorder à votre application l'accès à ses données.

Si l'utilisateur accorde l'accès à votre application en sélectionnant Autoriser l'accès, vous recevrez un rappel vers l'URL spécifiée par redirect_uri dans votre demande d'origine. Si le rappel réussit, il inclura un code d'autorisation que vous devrez échanger contre un access_token. Assurez-vous de valider que l’ state dans la réponse correspond à l’état que vous avez soumis dans la demande d’origine. Si une erreur s'est produite, vous recevrez la redirection avec le paramètre error .

Paramètres de réponse

Les paramètres sont reçus dans le cadre de la chaîne de requête.

Exemple de réponse

https://www.myserver.com/?code=acf3cabd-08c1-44db-88a9-4f785ec7c6ec&state=myteststate

Le code d'autorisation n'est valable que 5 minutes. Consultez Expiration du jeton pour obtenir une liste des durées de code et de jeton.

Maintenant que vous avez reçu le code d'autorisation, l'étape suivante consiste à l'échanger contre un access_token de Bluebeam. Pour ce faire, effectuez une requête POST au point de terminaison Token avec les paramètres ci-dessous.

Point de terminaison du jeton

https://api.bluebeam.com/oauth2/token

Paramètres de la requête

Les paramètres doivent être codés sous forme de formulaire.

Exemple de cURL

curl [https://api.bluebeam.com/oauth2/token](https://api.bluebeam.com/oauth2/token) \
-d grant_type=authorization_code \
-d code={code returned from previous step} \
-d redirect_uri={your redirect_uri} \
-d client_id={your client_id} \
-d client_secret={your client_secret} \
-d scope= offline_access {your requested scopes} \
-X POST

Exemple de réponse

{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJraWQiOiIybEczWnV2Q1pHRDFQX0FYclk4U0YyVVdmU2x3WHFpNWxZcUFzaHc4M05rIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjJ0Ml9nQWtxc2RvcDFWcWR1ajdLVUZwbXdNT1ZvU1VxcmZWVm5TOUZuMU0iLCJpc3MiOiJodHRwczovL3NpZ25pbi5ibHVlYmVhbS5jb20vb2F1dGgyL2F1c2JlcGh2azBlYkk3T09UNHg3IiwiYXVkIjoiYXBpOi8vYmItYWNtIiwiaWF0IjoxNzA4OTcwMzM2LCJleHAiOjE3MDg5NzM5MzYsImNpZCI6IjBvYWc2aGFjYWhnRUtqM0loNHg3IiwidWlkIjoiMDB1YngyeThtMDlwelVKRms0eDciLCJzY3AiOlsiZnVsbF9wcmltZSJdLCJhdXRoX3RpbWUiOjE3MDg5NzAzMTcsInN1YiI6InRvcnlhZGFtc0BwbS5tZSIsImJiaWQiOiJkNzE3MGZmYy03ZjlmLTQxZjYtOTY2ZS0xOTg1NTJlNzQwOTAifQ.S8m-cIfq8m19GtJ67skC8WM4bMWvJbAAr74A7g3HrUmH66M1_MN4MaDWjgcYjNFOI1zWsiZ5qm1HODLYY92lgUfzGuiYnkvpiJEKBtIUzLec2E2uEGE5HuW6FbyiX_SdGnSKeHlTr_FfiWGcpTYF816rI6q72kFm2J_3pKA-z_6REkNhI7qouRDRIHqT88tOE9KcjrF8_HsRAuixYAOlcGoVq3rvupvNVVaekoLyGiGWovXdJ-Wrx-1pKo0r7px2_Y8ew9OWEgYCX0u8pQvvPB6HAfF8dNCGTz_jFw9MbItu70rIniDoycILZKNxOcdKTLsCK7AC5doBcg9dV0OrHQ",
  "scope":"full_user offline_access",
  "refresh_token":"f5Mj16b7eVXwlY3Axc7TH2oEG_FPV1BrY05ht0uin6B"
}

Paramètres de réponse

Une fois que vous avez reçu un access_token, vous pouvez l'utiliser pour accéder à l'API. Pour utiliser un access_token, incluez-le dans l'en-tête Authorization :

Authorization: Bearer {a valid access_token}

Lors de l'envoi de l'en-tête d'autorisation, assurez-vous que le « B » dans « Bearer » est en majuscule. Si « Porteur » n’est pas en majuscule, vous obtiendrez une erreur.

Jetons d'accès

Un access_token est la chaîne réelle qui vous permet de faire des requêtes au nom de l'utilisateur. Chaque demande adressée à l'API Bluebeam doit inclure un access_token valide.

Chaque access_token est valable 60 minutes. Après l'expiration d'un access_token , un nouvel access_token peut être émis sans que l'utilisateur ait à se reconnecter en échangeant un refresh_token valide.

Rafraîchir les jetons

Le but des jetons d'actualisation
Les jetons d'actualisation sont un moyen pratique et sécurisé de faire des demandes authentifiées à l'API Bluebeam sans obliger les utilisateurs à se connecter pour chaque demande.
Les jetons d'actualisation sont toujours échangés contre 1) un jeton d'accès qui dure 1 heure et 2) un nouveau jeton d'actualisation qui restera valide tant qu'il sera utilisé au moins une fois tous les 7 jours.
Théoriquement, une fois qu'un utilisateur accorde manuellement l'accès à l'étape 1, vous pouvez continuellement échanger des jetons d'actualisation valides contre des jetons d'accès afin que l'utilisateur n'ait plus jamais à autoriser manuellement, à condition que vous échangiez des jetons d'actualisation au moins une fois tous les 7 jours.

Pour obtenir votre premier refresh_token, nous vous recommandons de demander la portée offline_access à l'étape 1, afin que vous receviez également un refresh_token.

Échangez votre refresh_token contre un nouveau access_token dans les 3600 secondes suivant l'obtention du dernier access_token. Lorsque vous échangez un refresh_token contre un access_token, un nouveau refresh_token vous est émis.

Contrairement à l' access_token, qui expire après 1 heure, un refresh_token reste valide indéfiniment, à condition qu'il soit utilisé au moins une fois tous les 7 jours. Un refresh_token deviendra invalide s'il n'est pas utilisé dans les 7 jours.

Stockez le refresh_token crypté et dans un endroit sécurisé. Si un refresh_token est perdu ou a expiré, vous devrez demander aux utilisateurs de s'autoriser à nouveau depuis le début du flux OAuth.

Pour échanger un refresh_token contre un nouvel access_token et refresh_token, effectuez une requête POST sur le point de terminaison Token :

Point de terminaison du jeton

https://api.bluebeam.com/oauth2/token

Paramètres de la requête

Les paramètres doivent être codés sous forme de formulaire.

Exemple de cURL

curl [https://api.bluebeam.com/oauth2/token](https://api.bluebeam.com/oauth2/token) \
-H Content-Type: application/x-www-form-urlencoded \
-H Authorization: Basic {base64 encoded string of client_id:client_secret} \ 
-d grant_type=refresh_token \
-d refresh_token={your refresh_token} \
-X POST

Révoquer les jetons d'actualisation
Les jetons d'actualisation peuvent être révoqués. Lorsqu'un refresh_token est révoqué, les utilisateurs devront s'autoriser à nouveau après l'expiration du access_token actuel.