Overview
In order to connect an app with the BlueConic REST API v2, the application must first be authorized. You can use the Client Credentials Flow to allow an external application to programmatically gain access to the REST API without user intervention. The external application runs on behalf of an existing BlueConic user.
Application scopes
As is usually the case with OAuth 2.0, the scopes of an application are not defined in a request but are defined within BlueConic when registering the application. Application scopes together with the user permissions of the user that has been configured to run on their behalf will determine which public APIs the application can access.
Access tokens
An access token can be obtained by the application when the application has successfully authenticated itself with a client ID and client secret to access the public API. The access token can be used in requests to access the API, but it is short-lived. Once the current access token has expired, the application will have to request a new access token in the same manner.
Protocol flow
The flow described below assumes that the 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.
-
The application makes a token request with its client credentials for authentication.
-
The application receives an access token if the application is successfully authenticated.
-
The application makes a request to the public API with the access token.
-
BlueConic validates the access token and if the access token is valid, BlueConic serves the request.
Implementation guide
Step 1. Register your application in BlueConic
To register your application, choose Settings > Access management > Applications from the BlueConic navigation bar. Click the Add application button.
Enter your application details in the Application information section.
The client ID and client secret are issued when the application is saved. Please store them securely, because your application will need to use these credentials to authenticate itself.
Configure the Application access
In the Application access section, you configure options including scopes and the IP addresses that are allowed to access BlueConic. You need to select a user for the ‘Run as user’ field here. The application will run on the selected user’s behalf and will inherit that user’s BlueConic role permissions. Only users with the ‘Authorize applications’ permission can be selected in the ‘Run as user’ field.
Save your settings and remember also to 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, 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 access token
To obtain an access token, call the /rest/v2/oauth/token endpoint.
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=client_credentials' \
--data-urlencode 'client_id=Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq' \
--data-urlencode 'client_secret=gmR64Qzo1mcxN5mp4IBpboP128bE9B4R'
Be sure to include the client ID and client secret in the request body for client authentication.
Set the grant_type in the request body to client_credentials.
Example token response
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 3600
}
If the request is successful, an access token is issued. The access token is short-lived and will expire in 1 hour. If the access token has expired, the application will have to perform the token request again to obtain a new access token.
Step 3. Call the 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 4. Revoke an access 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=2YotnFZFEjr1zCsicMWpAA' \
--data-urlencode 'token_type_hint=access_token' \
--data-urlencode 'client_id=Zl3QZFUGOKQrABbX2RoGwmgUDOiFAhLq' \
--data-urlencode 'client_secret=gmR64Qzo1mcxN5mp4IBpboP128bE9B4R'
Make sure 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.
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.