Authentication Guide

The first step is to request user authorization of your App. You will redirect the user to the Authorization endpoint where they will be asked to log in with their Studio credentials and grant permission to your App. To do this, make a GET request to the Authorization endpoint with the following parameters.

Authorization endpoint

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

Request parameters

Parameters must be passed in a query string.

Scopes for Studio Endpoints

Refresh tokens
Be sure to request 'offline_access' scope in your request to receive a refresh_token back. See more about refresh_tokens in Step 4, below.

Example request

1
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

User experience

Users will be directed to the Bluebeam Login page.

After logging in, the user may select Allow Access to grant your App access to their data.

If the user grants access to your App by selecting Allow Access, you will receive a callback to the URL specified by redirect_uri in your original request. If the callback is successful, it will include an authorization code that you will need to exchange for an access_token. Make sure to validate that the state in the response matches the state that you submitted in the original request. If an error has occurred, you will receive the redirect with error parameter.

Response parameters

Parameters are received as part of the query string.

Example response

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

The authorization code is only valid for 5 minutes. See Token expiration for a list of code and token durations.

Now that you've received the authorization code, the next step is to exchange it for an access_token from Bluebeam. To do this, make a POST request to the Token endpoint with the parameters below.

Token endpoint

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

Request parameters

Parameters must be form encoded.

cURL example

1
2
3
4
5
6
7
8
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

Example response

1
2
3
4
5
6
7
{
  "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"
}

Response parameters

Once you have received an access_token, you can use it to access the API. To use an access_token, include it in the Authorization header:

1
Authorization: Bearer {a valid access_token}

When sending the authorization header, make sure the "B" in "Bearer" is capitalized. If "Bearer" is not capitalized, you will get an error.

Access tokens

An access_token is the actual string that allows you to make requests on behalf of the user. Every request to the Bluebeam API must include a valid access_token.

Each access_token is valid for 60 minutes. After an access_token expires, a new access_token may be issued without requiring the user to log in again by exchanging a valid refresh_token.

Refresh tokens

The purpose of refresh tokens
Refresh tokens are a convenient and secure way to make authenticated requests to the Bluebeam API without requiring users to sign in for every request.
Refresh token are always exchanged for 1) an access_token that lasts 1 hour and 2) a new refresh_token that will stay valid as long as it is used at least once every 7 days.
Theoretically, once a user manually grants access in Step 1, you can continually exchange valid refresh tokens for access tokens so that the user never has to manually authorize again, provided that you are exchanging refresh tokens at least once every 7 days.

To get your first refresh_token, we recommend requesting the offline_access scope in Step 1, so that you will also receive a refresh_token.

Exchange your refresh_token for a new access_token within 3600 seconds of obtaining the last access_token. When you exchange a refresh_token for an access_token, a new refresh_token is issued to you.

Unlike the access_token, which expires after 1 hour, a refresh_token stays valid indefinitely, as long as it is used at least once every 7 days. A refresh_token will become invalid if it is not used within 7 days.

Store the refresh_token encrypted and in a secure place. If a refresh_token is lost or expired, you will need to ask users to authorize again from the beginning of the OAuth flow.

To exchange a refresh_token for a new access_token and refresh_token, make a POST request to the Token endpoint:

Token endpoint

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

Request parameters

Parameters must be form encoded.

cURL example

1
2
3
4
5
6
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

Revoking refresh tokens
Refresh tokens can be revoked. When a refresh_token is revoked, users will be required to re-authorize after the current access_token expires.