This article describes how to register and authorize external applications to access BlueConic securely. From the BlueConic settings menu (the gear icon), select Access management and then Applications to open the Applications tab. Here you can view and add applications that can access the BlueConic REST APIs.
At the top right of the main Applications tab is a Filters menu to narrow down the applications you want to view. You can apply any of the available filters; the table of applications updates with each filter you select. (If you want to save your applied filters for future use, click Save this filter from the Filters menu and name your filter set; that named set will then be accessible in the menu's Saved filters dropdown.)
All applied filters are listed in a row above the table of applications. You can remove any filter by clicking the X in its respective block in that row.
Adding an application to BlueConic
In the Applications page, click the Add an application button to enable an application to access BlueConic. Provide a name for the application and use the settings in the Applications page to define the application and its authorization settings.
Application information settings
OAuth 2.0 flow
Use these settings for authorizing an application to use the BlueConic REST API 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 BlueConic REST API. The authorization process in BlueConic for this access is built to OAuth 2.0 specifications.
Select the OAuth 2.0 flow you'll use to connect the app to BlueConic:
- Authorization code flow is meant for web apps executing on a server. It's considered the safest choice since the Access Token is passed directly to the web server hosting the Client without going through the user's web browser and risking exposure. Learn more about this authorization flow.
- Client credentials flow is meant for machine-to-machine (M2M) applications. This flow should be used when a Client is a machine that doesn’t involve end-users. The client authenticates themselves and gets a token. Examples are CLIs, daemons, or services running on a backend without a UI. The client credentials flow is easier to implement but lacks important security features and should only be used after making sure those security features are not needed. Use it only for absolutely trusted clients. Learn more about using the client credentials flow.
The method you choose here depends on the security protocol used by the external system.
Public client ID
This is a unique ID that is always retrievable and identifies the registered application client.
Client secret
The client secret grants you access to the BlueConic API through OAuth 2.0. Therefore it should not be shared with others and kept safely.
After a new secret has been generated, all future requests that use the old secret will fail.
Redirect URL
Required only for the Authorization code flow, the redirect URL(s) ensure the visitor will be redirected to appropriate locations. The redirect URL will receive the authorization code, which can be exchanged for the access token, after users successfully authenticate.
Application website URL
Required only for the Authorization code flow, the application's website URL is displayed to users during the OAuth 2.0 authentication.
Logo
Optional: Add a logo for the application. This logo visually represents the app's identity within BlueConic. Select a logo via the "Add icon from library" button or upload it from your computer.
- Aspect ratio: 1:1
- File formats accepted: SVG, PNG, JPG, JPEG, GIF
- Maximum file size: 1 MB
Application access settings
Scopes
Use the Scope settings to specify which parts of BlueConic the app can access. The connected app has only written access to the domains of the related users. So if a certain BlueConic user only has the right to Domain A, only Domain A can be accessed.
Allow IP address access
You can limit access by allowing requests only from specific IP addresses. Add one or more ranges of IP addresses that are allowed to access this app. You can use both ipv4 and ipv6.
Note: These are additional restrictions to the general IP allowlist under the Access management menu.
Using tokens (for authorization code flow)
OAuth 2.0 tokens provide this application access to the BlueConic API. The application scopes and permissions assigned to the user determine which objects the app can access.
Run as user (for client credentials flow)
Select a BlueConic user. Any actions performed by the app will be logged under that user and visible in the activity stream and audit event log. Only users with the 'Authorize applications' permission can be selected in the 'Run as user' field. Requests from the app that aren't allowed according to the user permissions are blocked.