Before your application can read or change data in a BIMcollab space, it needs permission. This article explains how to get an access token for the Connection API and the Documents API. Both APIs use the same sign-in process.
All examples use the Playground, our development space, so you can follow along safely.
How authorization works
The BIMcollab API uses OAuth 2.0 with the authorization code flow. Three parties are involved:
Your application, identified by its Client ID and client secret.
The user, who signs in with their own BIMcollab account.
The BIMcollab identity server, which checks both and provides required access tokens.
📝 Note: Your application only gets access to the data that the signed-in user can see. Access depends on the user's permissions, the projects they are a member of, and their role in each project.
Before you begin
If you've never called an API before, you don't need to write code to test an API. You can use specialized tools that send HTTP requests for you.
Postman: a free app with a friendly interface. It handles the OAuth 2.0 login (authentication mechanism) for you and is the easiest option for beginners.
cURL: A command-line tool available in most operating systems. The examples in this guide use cURL, so you can copy, paste, and adapt them.
💡 Tip: These are only general recommendations. There are many tools dedicated to API testing, so choose whichever works best for you.
API Client Credentials
For testing, start using the Playground credentials listed below. The BIMcollab Playground is a development space intended for testing integrations before you work with a private space. Setting up your account is a one-time process.
📝 Note: To sign in, first apply for a developer account to ensure you get access to the BIMcollab Playground space.
The Playground provides general client credentials that you can use together with your BIMcollab account to authenticate your application. For this, use these values:
Authorization URL |
|
Access token URL |
|
Callback URL |
|
Client ID |
|
Client secret |
|
Scope |
|
⚠️ Attention: Use these values exactly as shown. BIMcollab checks the Client ID, callback URL, and scope together; changing any of them will cause the login to fail
When you're ready to develop an integration for your own BIMcollab space, request your own Client Credentials.
Get an access token
Option A: Postman
Postman handles the login flow and stores the token, so you don't have to work with the raw authentication requests. Set it up once:
Create a new collection (here you will create all future requests)
Open the Authorization tab.
Set Auth Type to OAuth 2.0.
Under Configure New Token, fill in all fields using the Playground Client credentials from the previous section, including:
Token Name: enter a name of your choice for the token
Grant Type: select Authorization Code
State: this can be ignored for now
Client Authentication: select Send as Basic Auth header
Click Get New Access Token.
A browser window opens. Sign in with your BIMcollab user account, the account for which you set a password when you joined the Playground.
When authentication is complete, return to Postman and click Use Token.
Postman now attaches the access token to all requests in this collection automatically. It can also refresh the token when it expires.
Option B: cURL
If you prefer to work directly with API requests, you can perform the same authentication flow using cURL. The process consists of three steps:
Get an authorization code:
Sign in through the BIMcollab login page and receive a temporary authorization code. Open the following URL in your browser:
<authorization-url>?response_type=code&client_id=<client-id>&redirect_uri=<callback-url>&scope=openid%20offline_access%20bcf&state=abc123
If you are testing in the Playground, this would be:
https://playground.bimcollab.com/identity/connect/authorize?response_type=code&client_id=PlayGround_Client&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2FCallback&scope=openid%20offline_access%20bcf&state=abc123
Sign in with your BIMcollab account and accept the client permissions.
After accepting the permissions, your browser redirects to the callback URL. The address will look similar to:
http://localhost:5000/Callback?code=<authorization-code>&scope=openid%20offline_access%20bcf&state=abc123
Copy the value of <authorization-code>. You'll use it in the next step.
📝 Note: The page at localhost:5000 doesn't need to load. You only need the code from the address bar. The authorization code is valid for a short time and can be used only once.
Exchange the code for an access token
Send the <authorization-code> to the access token URL:
curl -X POST "https://playground.bimcollab.com/identity/connect/token" \
-u 'PlayGround_Client:<client-secret>' \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=<authorization-code>" \
--data-urlencode "redirect_uri=http://localhost:5000/Callback"
The response contains your tokens:
{
"id_token": "<id-token>",
"access_token": "<access-token>",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "<refresh-token>",
"scope": "openid offline_access bcf"
}
access_token: the token you use in your API requests.expires_in: how many seconds the access token stays valid.refresh_token: the token you use to get a new access token.
Refresh the access token
When the access token expires, request a new one with the refresh token. The user doesn't need to sign in again.
curl -X POST "https://playground.bimcollab.com/identity/connect/token" \
-u 'PlayGround_Client:<client-secret>' \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=<refresh-token>"
Use the access token
Add the <access-token> to the Authorization header of every request:
curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects" \
-H "Authorization: Bearer <access-token>"
This example uses the Connection API. It returns the projects the user has access to
Callback URLs and PKCE
For production, your application needs a valid callback URL that points to a web page or identity server that you control.
We discourage callback URLs that use a loopback address (such as localhost) or a dummy page, because they are less secure. If your application uses one in production, we ask you to also implement PKCE (Proof Key for Code Exchange).
PKCE adds a one-time secret to the sign-in process, so that a stolen authorization code can't be used. Learn more on oauth.com.
Find your space ID
Most of the requests from the Documents API require a <space-id>. This is the unique identifier (GUID) stored inside your access token. To read it:
Copy your access token. In Postman, go to Authorization > Manage Tokens.
Paste the token into a JWT decoder, such as jwt.io.
Look for the space ID in the decoded token.
⚠️ Attention: Access tokens give access to your data. Don't share them, and don't paste a real token into online tools unless you trust them. When possible, use a local JWT decoder.
Troubleshooting
Problem | Possible cause | Solution |
The sign-in page shows an error before you can sign in. | The Client ID, callback URL or scope doesn't match your credentials. | Copy the values again exactly as provided. Check that the callback URL is encoded correctly. |
The token request fails after sign-in. | The authorization code expired or was already used. | Repeat step 1 to get a new code, then exchange it right away. |
API requests return | The access token is missing or expired. | Check the |
API requests return | The signed-in user doesn't have access to the data. | Check the user's projects and roles in BIMcollab. |
The refresh request fails. | The refresh token expired. | Ask the user to sign in again. |