API

Selected functionality of BriefBuilder is exposed in the form of an API (application programming interface), which selected partners can use to exchange BriefBuilder model data. An API can be useful for linking BriefBuilder to CDE’s (common data environments), parametric design applications, and for dedicated add-ins (such as the BriefBuilder Revit add-in).

Documentation

The RESTful API is documented using Swagger and can be accessed here. Please note that you need a valid BriefBuilder user account to access the API documentation. If you do not have a user account, but would like to access the API documentation anyway, please contact us.

The API is designed to follow general REST principals. The following general error codes can be expected:
– 401 You are not authenticated.
– 403 You are not authorised for this resource.
– 404 Incorrect API url.
– 400 Incorrect API usage. Response contains a message regarding the nature of the error.
– 5XX BriefBuilder server error. This should generally not happen and indicates a fault in the API implementation. Our technical team will be alerted automatically when this happens.

We expect API consumers to act as a TolerantReader. These API operations will be expanded over time and you should be able to handle additional fields that are not yet documented as well as missing fields that are documented as much as possible.

Access control

The API can be tested from our swagger documentation. Actual API access for third-parties is granted through our OAuth2 authentication protocol for delegated acces and via HTTP Basic authentication for direct access for individual end users.

HTTP Basic Authentication

If you want to access your own data in BriefBuilder in an external application or tool you can use our HTTP Basic authentication option. All that is required is an existing BriefBuilder user account and your own explicit permission to enable this type of authentication for your account. If your environment requires two-factor authentication, HTTP Basic access is not possible. This option is only suitable for your own tools to access your own data.

To enable HTTP Basic authentication for our API access go to your profile settings and enable “Personal API access”

HTTP Basic Authentication code example

This simple option can be used as follows. An example using the curl command line tool:

curl -v -X GET --user YOUR_USERNAME:YOUR_PASSWORD \ 
-H "Accept: application/json" \
https://api-app.briefbuilder.com/ext/api/project

The – – user flag will set the HTTP “Authorization” header using the “Basic” auth scheme. For more information click here.

Delegated access control with OAuth2

Using this protocol, third-parties can request access the BriefBuilder data for a specific end-user, who has explicitly granted access for this by authenticating themselves on the BriefBuilder website. We are restricting the available OAuth2 authorization flows to Authorization code flow, using Bearer tokens for use cases where a third-party application provides additional functionality potentially to all BriefBuilder customers. This will require third-parties to exchange the access code for an access token using their client secret credentials in a back-end application.

If you would like to receive a set of client-credentials for creating a third-party application integration, please contact us so we can discuss the possibilities.

Authorization code example

Once you have received a set of client credentials from us you can use them in the following manner. This example uses cURL to show the HTTP interactions and may be implemented in any language.

The first step is to redirect your end user’s browser to the following URL. This will bring up the BriefBuilder authentication page if the user is not authenticated yet, or if they already are they will be redirected back to your REDIRECT_URI.

https://api-app.briefbuilder.com/oauth/authorize?grant_type=authorization_code&response_type=code&client_id=CLIENT_ID&state=STATE_TOKEN&redirect_uri=REDIRECT_URI

Where the STATE_TOKEN can be any string from your side to later on match requests and ensure the belong to this initial request. The REDIRECT_URI should match (one of the) redirect URI’s you supplied to us when requesting a client id and secret.

When the authenticated user is sent back to your REDIRECT_URI, it will contain the following additional query parameters:

?code=AUTHORIZATION_CODE&state=STATE_TOKEN

The AUTHORIZATION_CODE should be used in the next step when your backend application retrieves the final access code. The STATE_TOKEN matches the token sent in the initial request by the end user. Use the AUTHORIZATION_CODE as follows:

curl -X POST --location "https://api-app.briefbuilder.com/oauth/token" \
    -H "Accept: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI" \
    --basic --user CLIENT_ID:CLIENT_SECRET

If the AUTHORIZATION_CODE is valid and so our your own CLIENT_ID and CLIENT_SECRET, sent as in the Authentication HTTP header (base64 encoded) you will receive the access (and refresh) tokens:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600, 
  "scope": "read"
}

The refresh token may be used to get a new access token if it has expired:

curl -X POST --location "https://api-app.briefbuilder.com/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=CLIENT_ID&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN" \
    --basic --user CLIENT_ID:CLIENT_SECRET

To use the access_token to access the API (token can be used until it expires):

curl -v -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H "Accept: application/json" \
https://api-app.briefbuilder.com/ext/api/project/PROJECT_ID/export