BlueBeam OAuth (Third-Party Account) — Setup Guide

Overview Use this guide to register a BlueBeam app and connect it to your system as a "Third Party (BlueBeam)" OAuth account. The app enables end-users to:

• Access BlueBeam Cloud projects and documents
• Read/write BlueBeam Studio sessions and files
• Manage PDF markups and annotations
• Access BlueBeam Gateway for on-premise integrations
• Integrate with BlueBeam Revu document workflows

This document provides the exact permissions to grant, the redirect/authorization URLs to use, and the values to enter in your application. All values below use placeholders—replace them with your own.

---

1) Register a New App in BlueBeam Developer Portal

1. Sign in to BlueBeam Developer Portal at https://developer.bluebeam.com/
2. Navigate to My Applications → Create New Application.
3. Application Name: e.g., MinuteView Integration.
4. Application Description: Brief description of your integration purpose.
5. Application Type: Select Web Application.
6. Redirect URI:
   • Use your production callback URL, e.g. https://your-domain/MinuteView/PageGeneral/ServiceCallback.aspx
7. Requested Scopes: Select appropriate scopes (see scope selection below).
8. Click Create Application.

---

2) Collect App Credentials

From the application's Details page:

• Client ID: YOUR-BLUEBEAM-CLIENT-ID
• Client Secret: YOUR-BLUEBEAM-CLIENT-SECRET

Store the client secret securely as it contains sensitive authentication information.

---

3) OAuth 2.0 Scopes

BlueBeam uses scope-based permissions for API access:

Core Access Scopes

• read - Read access to user's BlueBeam data
• write - Write access to user's BlueBeam data
• delete - Delete access to user's BlueBeam data

Specific Resource Scopes

• projects - Access to BlueBeam Cloud projects
• sessions - Access to BlueBeam Studio sessions
• documents - Access to document management features
• markups - Access to PDF markup and annotation features
• gateway - Access to BlueBeam Gateway integrations

User Profile Access

• profile - Read user profile information
• email - Access to user's email address

---

4) Authorization & Token Endpoints

• Authorize endpointhttps://api.bluebeam.com/oauth2/authorize

• Token endpointhttps://api.bluebeam.com/oauth2/token

• User Info endpointhttps://api.bluebeam.com/oauth2/userinfo

---

5) Authorization Request

Use the Authorization Code flow:

GET https://api.bluebeam.com/oauth2/authorize
  ?response_type=code
  &client_id={ClientId}
  &redirect_uri={UrlEncodedCallbackUrl}
  &scope={SpaceSeparatedScopes}
  &state={RandomStateParameter}

Example scopes: read write projects documents profile email

---

6) Token Exchange (Server-Side)

When your app receives the code at the callback:

• POST to the token endpoint with:

  • grant_type=authorization_code
  • client_id={ClientId}
  • client_secret={ClientSecret}
  • code={authorization_code_from_callback}
  • redirect_uri={exact_same_redirect_uri}

You'll receive:

• access_token (use for API calls)
• refresh_token (use to get new access tokens)
• expires_in (token lifetime in seconds)
• token_type (typically "Bearer")

---

7) Testing Checklist

• Sign in with a user who has access to BlueBeam services.

• Call sample endpoints to validate each capability:

  • User Info: GET https://api.bluebeam.com/v1/user/me
  • Projects: GET https://api.bluebeam.com/v1/projects
  • Sessions: GET https://api.bluebeam.com/v1/sessions
  • Documents: GET https://api.bluebeam.com/v1/projects/{project_id}/documents
  • Markups: GET https://api.bluebeam.com/v1/documents/{document_id}/markups

• Confirm refresh token works and tokens are stored securely.

• Test file upload/download operations if applicable.

---

8) Security & Best Practices

• Treat Client Secret and refresh tokens as sensitive credentials; store in a secure credential store.
• Use HTTPS for all communications.
• Implement token refresh logic before tokens expire.
• Follow principle of least privilege - only request scopes you actually need.
• Monitor API usage to stay within rate limits.
• Validate all user input when processing BlueBeam data.

---

9) Troubleshooting

• Invalid redirect URI: Ensure the callback URL in the request exactly matches the registered redirect URI.
• Insufficient scope: Verify you've requested all necessary scopes for your use case.
• Token expired: Implement automatic token refresh using the refresh token.
• Access denied: Check user permissions for the specific BlueBeam projects and resources.
• Invalid client credentials: Verify your Client ID and Client Secret are correct.
• Rate limiting: Implement exponential backoff and respect rate limit headers.

---

10) Rate Limits & Usage Guidelines

BlueBeam APIs have rate limits to ensure service stability:

• Authentication API: 100 requests per minute per client
• Projects API: 60 requests per minute per user
• Documents API: 30 requests per minute per user
• Markups API: 100 requests per minute per user

Monitor response headers for rate limit information and implement appropriate backoff strategies.

---

11) BlueBeam-Specific Features

Studio Sessions

BlueBeam Studio sessions allow real-time collaboration:

• Create new sessions: POST /v1/sessions
• Join existing sessions: POST /v1/sessions/{session_id}/join
• Manage session participants: GET /v1/sessions/{session_id}/participants

PDF Markup Management

Handle PDF annotations and markups:

• Get document markups: GET /v1/documents/{document_id}/markups
• Add new markups: POST /v1/documents/{document_id}/markups
• Update existing markups: PUT /v1/markups/{markup_id}

Gateway Integration

For on-premise BlueBeam Gateway connections:

• Configure gateway endpoints
• Handle hybrid cloud/on-premise authentication
• Manage synchronized document libraries

---

Appendix — Example URL Templates

Replace placeholders and URL-encode parameters appropriately.

Authorization URL:

https://api.bluebeam.com/oauth2/authorize
  ?response_type=code
  &client_id={ClientId}
  &redirect_uri={UrlEncodedCallbackUrl}
  &scope=read%20write%20projects%20documents%20profile%20email
  &state={RandomState}

Token Exchange:

POST https://api.bluebeam.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={ClientId}
&client_secret={ClientSecret}
&code={CodeFromCallback}
&redirect_uri={ExactSameCallbackUrl}

Token Refresh:

POST https://api.bluebeam.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={ClientId}
&client_secret={ClientSecret}
&refresh_token={RefreshToken}

---

Common API Endpoints

• User Profile: https://api.bluebeam.com/v1/user/me
• Projects: https://api.bluebeam.com/v1/projects
• Project Documents: https://api.bluebeam.com/v1/projects/{project_id}/documents
• Document Details: https://api.bluebeam.com/v1/documents/{document_id}
• Document Markups: https://api.bluebeam.com/v1/documents/{document_id}/markups
• Studio Sessions: https://api.bluebeam.com/v1/sessions
• Session Details: https://api.bluebeam.com/v1/sessions/{session_id}

This configuration enables integration with BlueBeam Cloud, Studio sessions, PDF markup management, and Gateway connections for comprehensive construction document collaboration workflows.