Managing Console API authentication

The API that drives BDP Console’s functionality is publicly documented and available for our customers to invoke via code. All calls to it need to be properly authenticated using JSON Web Tokens (JWT) that can be acquired via the Credentials API.

Credentials UI v1

Previously, BDP Console was using the Password authentication flow to support machine-to-machine (m2m) applications. Under that scenario a BDP customer had to create a bot user in their account, retrieve a client ID and a client secret, and use all three to acquire a JWT. Customers who have enabled these credentials in the past will see the following panel in their Console account settings:

This method and the respective credentials still work for those who have been using them, however we strongly advise that customers upgrade to the current iteration where the only secret to be used by m2m applications is an API key which can be exchanged for a JWT as described below.

Credentials UI v2

The following view is available for all customers under BDP Console settings:

It is possible to have multiple different keys, and deletion of a key is also possible. When a new API key is created, the following view shows up:

This is a secret, equivalent to a username and a password combined, and should be handled as such at all times. As soon as you have an API key, it is straightforward to exchange it for a JWT. If you would do that using curl, it would look as follows:

curl \
  --header 'X-API-Key: <API_KEY>' \   https://console.snowplowanalytics.com/api/msc/v1/organizations/<ORGANIZATION_ID>/credentials/v2/token
Code language: HTML, XML (xml)

You can find your organization’s ID within the BDP Console URL:

The curl command above will return a JWT as follows:

{"accessToken":"<JWT>"}
Code language: JSON / JSON with Comments (json)

You may then use this access token value to supply authorization headers for subsequent api requests:

curl --header 'Authorization: Bearer <JWT>'
Code language: HTML, XML (xml)