Przewodnik po uwierzytelnianiu

Pierwszym krokiem jest zażądanie autoryzacji użytkownika dla Twojej aplikacji. Przekierujesz użytkownika do punktu końcowego autoryzacji, gdzie zostanie poproszony o zalogowanie się za pomocą danych uwierzytelniających Studio i przyznanie uprawnień Twojej Aplikacji. Aby to zrobić, wyślij żądanie GET do punktu końcowego autoryzacji z następującymi parametrami.

Punkt końcowy autoryzacji

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

Parametry żądania

Parametry muszą być przekazane w ciągu zapytania.

Zakresy punktów końcowych Studio

Odśwież tokeny
Upewnij się, że zażądasz zakresu „offline_access” w swoim żądaniu, aby otrzymać zwrotnie refresh_token. Więcej o refresh_tokens znajdziesz w Kroku 4, poniżej.

Przykładowe żądanie

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

Środowisko użytkownika

Użytkownicy zostaną przekierowani do strony logowania Bluebeam.

Po zalogowaniu użytkownik może wybrać Zezwól na dostęp, aby udzielić Twojej aplikacji dostępu do swoich danych.

Jeśli użytkownik udzieli dostępu do Twojej aplikacji, wybierając Zezwól na dostęp, otrzymasz wywołanie zwrotne na adres URL określony przez redirect_uri w Twoim oryginalnym żądaniu. Jeśli wywołanie zwrotne zakończy się pomyślnie, będzie ono zawierać kod autoryzacji, który należy wymienić na token dostępu. Upewnij się, że stan w odpowiedzi odpowiada stanowi, który przesłano w pierwotnym żądaniu. Jeśli wystąpił błąd, otrzymasz przekierowanie z parametrem error.

Parametry odpowiedzi

Parametry są odbierane jako część ciągu zapytania.

Przykładowa odpowiedź

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

Kod autoryzacji jest ważny tylko przez 5 minut. Zobacz Wygaśnięcie tokenu, aby zapoznać się z listą czasów trwania kodu i tokenu.

Teraz, gdy masz już kod autoryzacji, następnym krokiem jest wymiana go na token dostępu z Bluebeam. Aby to zrobić, wykonaj żądanie POST do Punktu końcowego tokenu z poniższymi parametrami.

Punkt końcowy tokenu

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

Parametry żądania

Parametry muszą być zakodowane jako formularz.

przykład 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

Przykładowa odpowiedź

{
  "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"
}

Parametry odpowiedzi

Po otrzymaniu access_token, możesz go użyć, aby uzyskać dostęp do interfejsu API. Aby użyć tokena `access_token`, dołącz go w nagłówku autoryzacji:

Authorization: Bearer {a valid access_token}

Podczas wysyłania nagłówka autoryzacji upewnij się, że „B” w „Bearer” jest pisane wielką literą. Jeśli „Bearer” nie będzie pisane wielką literą, otrzymasz błąd.

Tokeny dostępu

Ciąg access_token to rzeczywisty ciąg, który umożliwia przedstawianie żądań w imieniu użytkownika. Każde żądanie do Bluebeam API musi zawierać prawidłowy access_token.

Każdy access_token jest ważny przez 60 minut. Po wygaśnięciu access_token nowy access_token może zostać wydany bez konieczności ponownego logowania się użytkownika, wymieniając ważny refresh_token.

Odśwież tokeny

Cel tokenów odświeżania
Tokeny odświeżania to wygodny i bezpieczny sposób na uwierzytelnione żądania do interfejsu API Bluebeam, bez konieczności logowania się użytkowników przy każdym żądaniu.
Tokeny odświeżania są zawsze wymieniane na: 1) access_token, który jest ważny przez 1 godzinę oraz 2) nowy refresh_token, który pozostanie ważny tak długo, jak będzie używany co najmniej raz na 7 dni.
Teoretycznie, gdy użytkownik ręcznie udzieli dostępu w Kroku 1, można stale wymieniać prawidłowe tokeny odświeżania na tokeny dostępu, tak aby użytkownik nigdy więcej nie musiał ręcznie autoryzować, pod warunkiem, że wymieniasz tokeny odświeżania przynajmniej raz na 7 dni.

Aby uzyskać swój pierwszy refresh_token, zalecamy zażądanie zakresu offline_access w kroku 1, dzięki czemu otrzymasz również refresh_token.

Wymień swój refresh_token na nowy access_token w ciągu 3600 sekund od uzyskania ostatniego access_token. Podczas wymiany refresh_token na access_token, zostanie Ci wydany nowy refresh_token.

W przeciwieństwie do tokenu access_token, który wygasa po 1 godzinie, token refresh_token pozostaje ważny bezterminowo, pod warunkiem, że jest używany co najmniej raz na 7 dni. `refresh_token` stanie się niepoprawny, jeśli nie zostanie użyty w ciągu 7 dni.

Przechowuj refresh_token zaszyfrowany i w bezpiecznym miejscu. Jeśli `refresh_token` zostanie utracony lub wygaśnie, należy poprosić użytkowników o ponowną autoryzację od początku przepływu OAuth.

Aby wymienić refresh_token na nowy access_token i refresh_token, wyślij żądanie POST do punktu końcowego tokenu:

Punkt końcowy tokenu

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

Parametry żądania

Parametry muszą być zakodowane jako formularz.

przykład 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

Odwoływanie tokenów odświeżania
Tokeny odświeżania mogą zostać odwołane. Gdy token odświeżania zostanie unieważniony, użytkownicy będą musieli ponownie autoryzować się po wygaśnięciu bieżącego tokenu dostępu.