Administrator level authentication flow
- Bruno Combelles
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"}
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.
The API call is to a URI referencing both the user and the organisation
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
JWT.IO - JSON Web Tokens Introduction
Learning Locker and the Squirrel logo are trademark of Learning Pool 2020 | Learning Locker is licensed under GPL 3.0.