This page describes how to register and authorize external application to access BlueConic securely. From the BlueConic Settings menu (the gear icon), select Access management > Applications to open the Applications page. Here you can view and add applications that can access the BlueConic REST APIs.
It is important to note that for privacy and security reasons, BlueConic internal components, such as Connections and Notebooks, each have their own Application credentials and are also listed on this page. These Applications are read-only and have a system user of firstname.lastname@example.org. Internal applications have more stringent, internally-specified access restrictions and don't employ user permissions and application scopes. On the main Applications page, you will find filters in the top right corner to narrow down the applications you want to view. To hide these internal components, use the "Defined by" filter to see only "User defined" applications.
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.
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.
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.
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
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. Requests from the app that aren't allowed according to the user permissions are blocked.