Guida all'autenticazione

Il primo passo è richiedere l'autorizzazione dell'utente per la tua App. L'utente verrà reindirizzato all'endpoint di autorizzazione, dove gli verrà chiesto di accedere con le credenziali dello Studio e di concedere l'autorizzazione alla tua app. Per fare ciò, effettuare una richiesta GET all'endpoint di autorizzazione con i seguenti parametri.

Endpoint di autorizzazione

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

Parametri di richiesta

I parametri devono essere passati in una stringa di query.

Ambiti per endpoint di Studio

Aggiorna i token
Assicurati di richiedere l'ambito 'offline_access' nella tua richiesta per ricevere indietro un refresh_token. Per maggiori informazioni sui refresh_token, vedere il passaggio 4 di seguito.

Esempio di richiesta

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

Esperienza utente

Gli utenti verranno indirizzati alla pagina di accesso di Bluebeam.

Dopo aver effettuato l'accesso, l'utente può selezionare Consenti accesso per concedere alla tua app l'accesso ai suoi dati.

Se l'utente concede l'accesso alla tua app selezionando Consenti accesso, riceverai una callback all'URL specificato da redirect_uri nella tua richiesta originale. Se il callback ha esito positivo, includerà un code di autorizzazione che dovrai scambiare con un access_token. Assicurati di convalidare che lo state nella risposta corrisponda allo stato inviato nella richiesta originale. Se si è verificato un errore, riceverai il reindirizzamento con il parametro error .

Parametri di risposta

I parametri vengono ricevuti come parte della stringa di query.

Esempio di risposta

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

Il codice di autorizzazione è valido solo per 5 minuti. Per un elenco delle durate del codice e del token, vedere Scadenza del token .

Ora che hai ricevuto il code di autorizzazione, il passo successivo è scambiarlo con un access_token da Bluebeam. Per fare ciò, invia una richiesta POST all'endpoint Token con i parametri indicati di seguito.

Endpoint token

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

Parametri di richiesta

I parametri devono essere codificati in formato.

esempio 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

Esempio di risposta

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

Parametri di risposta

Una volta ricevuto un access_token, puoi utilizzarlo per accedere all'API. Per utilizzare un access_token, includilo nell'intestazione Authorization:

Authorization: Bearer {a valid access_token}

Quando si invia l'intestazione dell'autorizzazione, assicurarsi che la "B" di "Bearer" sia scritta in maiuscolo. Se "Portatore" non è scritto in maiuscolo, verrà visualizzato un errore.

Token di accesso

Un access_token è la stringa effettiva che consente di effettuare richieste per conto dell'utente. Ogni richiesta all'API Bluebeam deve includere un access_token valido.

Ogni access_token è valido per 60 minuti. Dopo la scadenza di un access_token , è possibile emetterne access_token nuovo senza richiedere all'utente di effettuare nuovamente l'accesso, scambiando un refresh_token valido.

Aggiorna i token

Lo scopo dei token di aggiornamento
I token di aggiornamento rappresentano un modo comodo e sicuro per effettuare richieste autenticate all'API Bluebeam senza richiedere agli utenti di effettuare l'accesso per ogni richiesta.
I token di aggiornamento vengono sempre scambiati con 1) un access_token della durata di 1 ora e 2) un nuovo refresh_token che rimarrà valido finché verrà utilizzato almeno una volta ogni 7 giorni.
In teoria, una volta che un utente concede manualmente l'accesso nel passaggio 1, è possibile scambiare continuamente token di aggiornamento validi con token di accesso, in modo che l'utente non debba più autorizzare manualmente, a condizione che si scambino token di aggiornamento almeno una volta ogni 7 giorni.

Per ottenere il tuo primo refresh_token, ti consigliamo di richiedere l'ambito offline_access nel passaggio 1, in modo da ricevere anche un refresh_token.

Scambia il tuo refresh_token con un nuovo access_token entro 3600 secondi dall'ottenimento dell'ultimo access_token. Quando si scambia un refresh_token con un access_token, viene emesso un nuovo refresh_token .

A differenza access_token, che scade dopo 1 ora, un refresh_token rimane valido indefinitamente, purché venga utilizzato almeno una volta ogni 7 giorni. Un refresh_token non sarà più valido se non verrà utilizzato entro 7 giorni.

Conservare il refresh_token crittografato e in un luogo sicuro. Se un refresh_token viene perso o è scaduto, sarà necessario chiedere agli utenti di autorizzarlo nuovamente dall'inizio del flusso OAuth.

Per scambiare un refresh_token con un nuovo access_token e refresh_token, effettuare una richiesta POST all'endpoint Token:

Endpoint token

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

Parametri di richiesta

I parametri devono essere codificati in formato.

esempio 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

Revoca dei token di aggiornamento
I token di aggiornamento possono essere revocati. Quando un refresh_token viene revocato, gli utenti dovranno autorizzarlo nuovamente dopo la scadenza dell'access_token corrente.