Authorization and Tokens

How to send authorized requests to BitBroker APIs

All the API sets within BitBroker require authorization by callers. Whilst the process for authorization is common across the APIs, the context and reasons for authorization differ:

Coordinator API - needed to administer a BitBroker instance
Contributor API - needed to contribute data to a designated entity type
Consumer API - needed to access data via a policy definition

Except in some development modes, there is no access to BitBroker services without authorization and hence without having a corresponding authorization token.

Authorizing API calls

When you have obtained the relevant authorization token (see below), you can use it to authorize API calls by using a specified HTTP header attribute. The same authorization header structure is used for all three BitBroker API sets.

x-bbk-auth-token: your-token-will-go-here

The header must be exactly as it appears here, with the same casing and without spaces. If you do not correctly specify the authorization header, or you use an invalid authorization token, you will get an HTTP/1.1 401 Unauthorized error.

Testing your Authorization Token

It can be useful to make test calls to the API to check that your authorization token is valid and that your authorization header is formatted correctly.

The base end-point of all the three API servers respond with a small announcement. Like all BitBroker API end-points, these require a working authorization to be in place. Hence, this announcement can be used for testing or verification purposes.

See the section on testing installations for Kubernetes or local modes for more details.

You are encouraged to make successful test calls to these end-points before launching into more complex scenarios.

Obtaining an Authorization Token

The method used to obtain an authorization token differs across the three API sets. However, once you have a authorization token, the mechanics of authorization are the same. All authorization tokens are in the form of a long hexadecimal string, such as:

4735d360-dc03-499c-91ce-68dfc1554691.5d5c9eab-1d9c-4c88-9478-9f4ab35568a7.423c9101-315a-4929-a64c-9b905837799c

These authorization tokens should be kept by their owner in a secure location and never shared with unauthorized users.

BitBroker does not retain an accessible copy of authorization tokens. If tokens are lost, new tokens will have to be generated as per the instructions below. The lost authorization tokens will then be rescinded.

Obtaining a Coordinator Authorization Token

Coordinator authorization tokens are required to authorize calls to the Coordinator API. This API is used to perform administrative services for a BitBroker instance.

Coordinator authorization tokens are obtained by utilizing end-points on the Coordinator API, in order to promote a user to coordinator status. To do this you must first create a new user and then you must promote that user to be a coordinator.

Once you promote a user to be a coordinator, then their coordinator authorization token will be returned in the body of the response to that API call.

Fresh BitBroker installations come with a bootstrap coordinator user and with an associated bootstrap coordinator token.

It is possible, but not recommended, to use the bootstrap user in normal operation. Instead, you should use the bootstrap coordinator token to create your own master coordinator user and then utilize their token for further operations.

If a coordinator authorization token is lost, then a new token will have to be generated. This can be done by first demoting the user from being a coordinator and then promoting them again. Note that, in this scenario, the old coordinator authorization token will be rescinded.

Obtaining a Contributor Authorization Token

Contributor authorization tokens are required to authorize calls to the Contributor API. This API is used to contribute data to a designated entity type.

Contributor authorization tokens are obtained by utilizing end-points on the Coordinator API, in order to create a connector on a given entity type.

Once the connector is created, then its contribution authorization token will be returned in the body of the response to that API call. More information about data connectors and data contribution is available in the key concepts section of this documentation.

If a contributor authorization token is lost, then a new token will have to be generated. This can be done by first deleting the connector and then creating it afresh. Note that, in this scenario, the old contributor authorization token will be rescinded.

Losing contributor authorization tokens can cause major disruption. Since the resolution involves deletion and the re-creation of the connector, all the associated data records will be lost and will have to be reinserted into the catalog by the new connector.

Recreating a connector which was previously deleted, will result in the same connector ID, if the new connector has the exact same name.

It is expected that the coordinator user, who creates the data connector, will distribute the contribution authorization token in a secure manner to the relevant party.

Obtaining a Consumer Token

Consumer authorization tokens are required to authorize calls to the Consumer API. This API is used to access data via a policy definition.

Consumer authorization tokens are obtained by utilizing end-points on the Coordinator API. To do this you must create an access, which is a link between a user and a policy definition.

Once you create such an access, then the consumer authorization token will be returned in the body of the response to that API call.

If a consumer authorization token is lost, then you can reissue the access to obtain a new token. Note that, in this scenario, the old consumer authorization token will be rescinded.