Help Center

Overview

If you have an external software application that needs to communicate with BlueConic, you will want to allow access to the BlueConic REST API v2. In order to access the BlueConic API, an application must first be authorized. The authorization process in BlueConic for this access is built to OAuth 2.0 specifications. A BlueConic user can grant an application access to the public BlueConic API via the Authorization Code Flow. Only users with the permission to authorize applications in BlueConic can grant an application access.

Scopes

Note that scopes are not defined in the authorization request, which is usually the case in OAuth 2.0. The scopes of an application are defined within BlueConic when registering an application in the BlueConic Settings > Applications window. The application scopes together with the user permissions of the user that granted access will determine which public APIs the application can access.

Access and refresh tokens

An access and refresh token can be obtained by the application when you have successfully authenticated yourself and authorized the application to access the public BlueConic API. The access token can be used in requests to access the API, but it is short-lived. The refresh token can be used to obtain a new access token when it has expired. Keep in mind that a new refresh token is returned as well, and the old refresh token is invalidated once used, because Refresh Token Rotation is supported by default.

For improved security, the Proof Key for Code Exchange (PKCE) extension for OAuth 2.0 is enforced. You will therefore be required to supply a code verifier and code challenge during authorization.

Protocol flow

The standard flow described below assumes that your application has been registered in BlueConic (see steps below). Application registration is required to be able to authenticate the application with the client ID and client secret.

1. The application makes an authorization request and redirects to the authorization server.
2. The application receives an authorization code from the authorization server when you have authenticated yourself and granted the application access.
3. The application makes a token request to exchange the authorization code for an access and refresh token.
4. The application receives an access and refresh token if the application was successfully authenticated (with the client id and client secret) and the authorization code was valid.
5. The application makes a request to the public API with the access token.
6. BlueConic validates the access token and if the access token is valid, serves the request.

This diagram illustrates the standard authorization code flow in BlueConic.

 

Implementation guide

Step 1: Register your application in BlueConic

You can register your application in BlueConic by going to Settings > Access management > Applications. Click the Add application button to get configure access for your application.

The client ID and client secret are issued when the application is saved. Please store them securely, as your application will need to use these credentials to authenticate itself.

When registering your application, you will have to enter a redirect URL and your application website. The redirect URL will receive the authorization code or any errors in its query parameters. The redirect URL is not allowed to contain fragments (#). For example, https://www.example.com/callback#here is not allowed.

You can also configure the application access settings here including application scopes and which IP addresses are allowed.

Remember to also change the status of the application to ON when you are ready to use the application using the toggle at the top. If the application status is OFF, then the client authentication will fail later on, and the access/refresh tokens also won’t work if there are any for the application.

Step 2: Request an authorization code

You can start the Authorization Code Flow by calling the /rest/v2/oauth/authorize endpoint.

Example authorization request

curl -X GET 'https://www.{your-tenant-name}.blueconic.net/rest/v2/oauth/authorize?response_type=
code&client_id=Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq&
redirect_uri=https%3A%2F%2Fwww.example.com%2Fcallback&
code_challenge=4MwafmutlwDy7ly8QOtO-bUvSVzU3I_OQEDgmB3Pn5A&code_challenge_method=S256&state=xyz'

You will be redirected to the authorization server where you will have to authenticate yourself first. If you were already logged into BlueConic, then you will not have to log in again for authentication. On the authorization page, you can either deny or grant the application access. If access is granted, then you get redirected to the provided redirect URL with the authorization code added to the query parameters. The redirect URL in the query parameters must match the redirect URL of the registered application in BlueConic from Step 1.

Example redirect URL with authorization code

www.example.com/callback?state=xyz&code=SplxlOBeZQQYbYS6WxSbIA

Your application will need to be able to receive this redirect request and the application will need to check if the state query parameter matches the state from the original authorization request. If it does not match, then a cross-site request forgery (CSRF) attack might have taken place.

The authorization code is single-use and expires after 10 minutes.

Step 3: Request an access and refresh token

You can exchange the authorization code from previous step for an access and refresh token by calling the /rest/v2/oauth/token endpoint.

Example access token request

curl --location 'https://www.{your-tenant-name}.blueconic.net/rest/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=SplxlOBeZQQYbYS6WxSbIA' \
--data-urlencode 'redirect_uri=https://www.example.com/callback' \
--data-urlencode 'code_verifier=ea0d4b371a40528a86fff7c6af4b1f4b1239862f89771b5dcf409554' \
--data-urlencode 'client_id=Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq' \
--data-urlencode 'client_secret=gmR64Qzo1mcxN5mp4IBpboP128bE9B4R'

You will need to include the client ID and client secret in the request body for client authentication.

The grant_type in the request body should be set to authorization_code and the authorization code from Step 2 should be added to the request body as well. The redirect URL in the request body must match the redirect URL from the original authorization request.

Example token response

{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIB",
"token_type": "Bearer",
"expires_in": 3600
}

If the request was successful, then both access and refresh tokens are issued. The access token is short-lived and will expire in 1 hour. The refresh token has no expiration date, but upon use it will be invalidated and a new refresh token is issued as we support Refresh Token Rotation by default.

Step 4: Call a public API with the access token

You can now access the public API with your application by adding the access token to the authorization header.

Example API request with access token

curl -X GET "https://www.{your-tenant-name}.blueconic.net/rest/v2/segments" \
-H "Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA"

Step 5: Refresh an access token

In case the access token has expired, your application can get a new access token by presenting the associated refresh token to the /rest/v2/oauth/token endpoint.

Example refresh token request

curl --location 'https://www.{your-tenant-name}.blueconic.net/rest/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=tGzv3JOkF0XG5Qx2TlKWIB' \
--data-urlencode 'client_id=Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq' \
--data-urlencode 'client_secret=gmR64Qzo1mcxN5mp4IBpboP128bE9B4R'

You will need to include the client ID and client secret in the request body for client authentication. The grant_type in the request body should be set to refresh_token, and the refresh token value has to be added to the request body as well. The token response is the same as Step 3.

Step 6: Revoke an access/refresh token

To revoke tokens, you have to call the /rest/v2/oauth/revoke endpoint.

Example revoke request

curl --location 'https://www.{your-tenant-name}.blueconic.net/rest/v2/oauth/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=tGzv3JOkF0XG5Qx2TlKWIB' \
--data-urlencode 'token_type_hint=refresh_token' \
--data-urlencode 'client_id=Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq' \
--data-urlencode 'client_secret=gmR64Qzo1mcxN5mp4IBpboP128bE9B4R'

You will need to include the client ID and client secret in the request body for client authentication. The token to revoke has to be added to the request body, and you can optionally add a token_type_hint to specify the token type for optimized lookup. Revoking a token revokes all active access tokens and the valid refresh token that originate from the same authorization code grant.

Tokens can also be revoked from within the BlueConic UI. Token revocation within BlueConic can be performed in two places:

1. Application page (BlueConic Settings > Access management > Applications)
   Active tokens are displayed at the bottom of the application page. You can revoke tokens by clicking the ‘Revoke token’ button in a table row, which will appear on hover.
   

2. Account settings
   You can revoke your personal tokens from the account settings. Only your own tokens are visible and can be revoked. This enables users to manage their own tokens without requiring the ‘Applications’ permission to access the Application page.
   

Learn more about using the REST API v2 with OAuth 2.0

See the article Using the BlueConic REST API for details on configuring BlueConic so your external OAuth 2.0 apps can authenticate and use the REST API.