Whilst many of the common API calls are authorised for the standard clients, some will be restricted to Administrative users. This page describes how to programmatically gain authorization to perform administration tasks using the APIs.

The Stream Data Cloud authorization system is based on bearer JWT. Users will be given a site level token when they log on the platform and an additional organisation level token when they select their organisation.

The flow to is as follows:

 1 - Authentication

Authentication will be performed for a Stream Data Cloud user with the correct level of access to the target organisation.

The Authentication API calls uses a Basic Authorization mechanism: user name and password are encoded in Base 64.

E.G. in JavaScript

authorizationString = window.btoa('YOUR_USERNAME:YOUR_PASSWORD')

The call to the authentication API is made as follows:

POST /api/auth/jwt/password HTTP/1.1
Host: {{hostname}}
Authorization: Basic {{authorizationString}}

If the authentication is successful, the response will be a site-level JWT. The user has been recognised and will now be able to :

• Perform administrative tasks at site level (e.g. invite users)

• Access one of the organisations.

2 - Enter the organisation

Using the site-level JWT obtained in the previous step, an organization-level JWT can be retrieved by calling the organisation access API.

The body (payload) for that call is a JSON document defining the organisation to be entered:

E.G.

{"organisation": "5e83028eb44bd34e19de90b1"}

POST /api/auth/jwt/organisation HTTP/1.1
Host: {{hostname}}
Authorization: Bearer {{siteJWT}}
Content-Type: application/json

{"organisation": "{{orgID}}"}

If the user is authorized to access the organisation, the response will be an organisation-level JWT

3 - Get to work

All the operations authorized by the role(s) of the user can now be performed using the organisation-level JWT.

Examples:

Assign roles to a user within the organisation

Payload: A JSON document defining the variable roles as an array containing all the role IDs to be assigned to the user.

        {
            "roles": [
                "5e83028eb44bd34e19de90b3",
                "5e83028eb44bd34e19de90b2",
                "61669fdcd5d6c70b6ff3798e"
            ]
        }

The API call is to a URI referencing both the user and the organisation

PATCH /api/v2/users/{{userID}}/organisationSettings/{{organisationID}} HTTP/1.1
Host: {{hostname}}
Authorization: Bearer {{organisationJWT}}
Content-Type: application/json

            {
                "roles": {{roleArray}}
            }

The call will patch the user definition. If the role assignment is successful, the response will be the updated item in the organisationSettings array.

 Related articles

https://en.wikipedia.org/wiki/Basic_access_authentication

https://jwt.io/introduction