Authentication

Approach

It is possible to restrict access to the API with JSON Web tokens (JWT). The general approach with using JWT as authentication method is as follows:

  1. A JWT is requested by submitting credentials to the API.
  2. In case the credentials are valid, a JWT is generated by WHATS'ON.
  3. The JWT is returned to the client.
  4. For each request, the JWT must be included in the header.
  5. WHATS'ON reads the JWT for every request and validates it before processing the message.
  6. A response message is returned.

Screenshot

Requesting a token

To request a token, a POST call must be sent to the to the /login path of the API. The body of this call needs to contain the credentials of the user accessing the API in the following format:

POST /login

{
    "username": "api-user",
    "password": "won1"
}

All calls should be sent over HTTPS to ensure that usernames and passwords are not sent unencrypted! See Setting up HTTPS for details on how to configure HTTPS communication.

The response of the login call contains following information:

  • statusCode: the status code is 0 in case of successful authentication.
  • message: a response message which contains the description in case of errors.
  • token: the access token to be sent as part of the header for any calls to the API.
  • service: name of the service to which the user is authorized.
{
    "statusCode": "0",
    "message": "Authentication successful",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InBzaSIsInBhc3N3b3JkIjpudWxsLCJpYXQiOjE1MDc3NDk1MDN9.SWUKmXP1P4uTu323QFmhBwnuP9eBDPJqKZa2jWiXk7c",
    "service": "Rights Business API"
}

Authentication

Once a token is requested, the token must be included in the authorization header of every REST call using the following format:

Authorization: Bearer <token>

An actual request would look as follows:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJ1c2VybmFtZSI6InBzaSIsInBhc3N3b3JkIjpudWxsLCJpYXQiOjE1MDc3NDk1MDN9.SWUKmXP1P4uTu323QFmhBwnuP9eBDPJqKZa2jWiXk7c

The same token can be re-used as long as it has not expired yet.

In case any problems occur with the authentication, the following status codes can be returned

Status code Description
401 Unauthorized This response is returned in the following cases: 1. no permissions to read or update the resource. 2. the user is not an API user.
403 Forbidden This response is returned in the following cases: 1. the request does not contain a JWT token (or contains an invalid JWT token). 2. the JWT token has expired. 3. wrong credentials.

Configuration

Service settings

In the service settings, it is possible to indicate the authentication level. Options are:

  • No Authentication
  • User based JWT

When the User based JWT authentication method is used, the user must have access to the API and have a token.

Additionally, it is possible to set the validity period for the token or to set it to Never expire.

Screenshot

Permission navigator

In the permission navigator, it is possible to set the access level of the user in the field Access type:

  • API: only allows the user to access the REST API, i.e. the user cannot log into WHATS'ON but can execute calls towards the REST API services.
  • UI: only allows the user to access the user interface of WHATS'ON, i.e. the user can log into WHATS'ON but cannot send calls towards the REST API services.
  • UI and API: there are no restrictions for this user. The user can access the user interface and the REST API of WHATS'ON.

Screenshot

API user account permissions

Additionally, when a user logs in with a username and password, the permissions as they are set on the role of that user in WHATS’ON are honoured. Generally, the user needs the permissions that would be needed to edit the concept of the API in WHATS'ON.

For example, when the user does not have the Program Creation Management permission and they send a POST call to create a product, the following response is sent back to inform about the permissions:

{
  "statusCode": "403",
  "message": "The account being accessed does not have sufficient permissions to execute this operation.",
  "timestamp": "2021-07-06T09:23:56Z"
}