Help Center

Developers creating applications that communicate with BlueConic can use the updated BlueConic REST API v2 at rest.apidoc.blueconic.com.

BlueConic REST API v2

The recently updated BlueConic REST API offers access to a wealth of resources to interact with BlueConic visitor profiles, segments, interactions, and audit events via OpenAPI and OAuth 2.0 authorization flows, making the interconnection between various services more secure, intuitive, and reliable than ever before. 

Developers can use OAuth 2.0, the industry-standard protocol for authorization, to authorize apps in BlueConic and get started using the BlueConic REST API v2.

Authorizing an application to use the BlueConic REST API v2 via OAuth 2.0

If you have an external software application that needs to communicate with BlueConic, you will want to allow access to the current BlueConic REST API. The authorization process for this access is built to OAuth 2.0 specifications.

To make use of the BlueConic REST API with OAuth 2.0, you need to complete the following steps:

1. Configure BlueConic so the external OAuth 2.0 application can authenticate and use the REST API. This means that you have to:
   • Have a BlueConic user with a role that has the "Applications" permission, such as Application Manager. This user can configure the details of the external application in BlueConic. 
     
   • Have a BlueConic user with a role that has the "Authorize applications" permission. This user can authorize the external application via the redirect page served by the authentication server. 
   • Configure the external application in BlueConic via BlueConic settings > Access management > Applications so BlueConic can store the application ID (public client ID) and the client secret. These properties are used by the external app to perform the initial request for an authorization code. 
     
      
2. Develop an application that can execute OAuth 2.0 REST requests. Specifically that means an application that is able to:
   • Generate a code verifier and code challenge.
   • Store the public client ID and the client secret as configured in BlueConic (see above).
   • Request an authorization code from the BlueConic Authorization server. Include the verifier and challenge in the request.
   • Show the user the redirect page that the authorization server serves so that the user can authenticate with credentials and consent to giving the application BlueConic REST API access.
   • Receive the authorization code from the BlueConic authorization server.
   • Use the authorization code to request an access token (and refresh token) from the BlueConic authorization server. Include the code challenge verifier in the request.
   • Use the authorization code to request an access token and refresh token. 
   • Use the access token to perform rest requests. 
   • Revoke access if the user of the app so chooses (meaning that after this revocation, a new authorization grant is required to use the REST API).
   • Handle refresh token rotation—meaning that whenever a new access token is requested using the refresh token, that along with the new access token a new refresh token is also supplied. 
   • Handle all possible responses from the BlueConic REST API appropriately. 

Learn more about adding an application to BlueConic and authorizing access via the client credentials flow or authorization code flow.