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.

---

Network Requirements

The BlueBeam account setup involves an OAuth flow where part of the process happens in the user's browser and part happens on the MinuteView server itself. After the user authenticates with BlueBeam and is redirected back to MinuteView, the server exchanges the authorization code for a token by calling BlueBeam's API directly. This means the MinuteView server must have outbound internet access to the following domains.

Required Firewall / Proxy Whitelist

The following domains must be accessible via HTTPS (port 443) from the server where MinuteView is installed. Whitelist the domain(s) that match your BlueBeam region:

Domain	Region	Purpose
api.bluebeam.com	US	OAuth token exchange, token refresh, and BlueBeam API calls
api.bluebeamstudio.com.au	Australia	OAuth token exchange, token refresh, and BlueBeam API calls
api.bluebeamstudio.eu	Europe	OAuth token exchange, token refresh, and BlueBeam API calls
authserver.bluebeam.com	Legacy (all regions)	Token exchange for deprecated BlueBeam OAuth v1

Server Access Required

These domains must be reachable from the server, not just from the user's PC. The user's browser handles the initial login redirect, but the token exchange and all subsequent API calls are made server-side. If the server cannot reach these domains, the account setup will fail with a connection error even though the BlueBeam login page loaded successfully in the browser.

---

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

• "Failed to retrieve authentication token" / Connection error: The most common cause is that the MinuteView server does not have outbound internet access. The BlueBeam login page loads in the user's browser (which has internet), but the token exchange happens on the server. If the server is behind a firewall without internet access, this step fails. See Network Requirements above for the domains that must be whitelisted.
• 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.