Skip to main content

Authentication

The image shows the journey from the end user to the MSL Edge API.

Client authentication flow

MSL Edge is to whitelist the client partner public IP address/range to allow access to the platform.

Client Credentials​

Use the provided username and password for the token request as documented here. If the criteria for a valid username, password and IP address are satisfied the API returns a token.

Authorization Header​

Once the API returns a token, the next step is to use it for subsequent API requests. The example shows the Authorization header and the value that must be provided to have an API authorization on an endpoint.

On receiving the token, the platform initiate the validation. It is to ensure requests are from allowed IP addresses and the token is valid.

Password Expiry​

After successful authentication, the API returns an access token. The token payload includes the password_expire_days field, which indicates the number of days remaining before the password expires. This value should be monitored so the password can be updated proactively before expiry using the POST /manage/password to avoid authentication failures.

When changing a password, the new password is validated against previously used passwords. If the new password matches a previously used one, the request is rejected with error code 4010001.

Once the password has expired:

  • Any attempt to obtain a new access token using the expired credentials will be rejected with HTTP Status Code 401 and error_code 4010001.
  • Authentication will not succeed until the password has been updated successfully.

IP Whitelising​

When a request to generate a new token is received, the IP from where the request originated is also recorded and used in the token generation. When credentials for making requests to the APIs are being created, a number of IPs or IPv4 ranges are to be provided in order for generation of tokens to be successful. When a request is received, the IP of the request is checked against the IPs or IPv4 ranges provided, and if there is a match, a token is generated accordingly.

Suspicious IP Protection​

Although an IP address may be whitelisted to authenticate and retrieve tokens, it is not automatically exempt from the Suspicious IP protection mechanism.

This feature monitors high-velocity authentication activity from a single IP address. If a burst of token requests occurs in a very short period of time - particularly when many authentication attempts are made in rapid succession - the IP address will be temporarily throttled or blocked.

When this protection is triggered:

  1. The IP address is temporarily blocked for a short cooling-off period (around 15 minutes).
  2. Additional authentication attempts from that IP during the block period will fail.
  3. Requests will return error code 4010001 in order to avoid revealing whether the provided credentials were valid or invalid.

Brute Force Protection​

The Brute Force Protection mechanism is designed to detect repeated failed authentication attempts.

If multiple consecutive authentication attempts are made using incorrect credentials, the system will assume that the account may be under attack and will temporarily block further login attempts originating from the same IP address for that user.

When this protection is triggered:

  1. Further authentication attempts from the offending IP will be blocked.
  2. Requests will return error code 4010001 to prevent disclosing whether the provided credentials were correct.
  3. A notification email will be sent to the designated contact configured during programme setup.
  4. The email will contain a link that allows the designated contact to remove the IP block if the activity was legitimate.

To ensure reliable authentication and avoid triggering security protections, follow the practices below when integrating with the authentication service.

Avoid Rapid Token Requests​

Applications should avoid sending large bursts of token requests in a very short period of time.

  1. Request a token only when required
  2. Reuse the token until it expires
  3. Avoid requesting a new token for every API call

Access tokens remain valid for 15 minutes, so they should be cached and reused.

Implement Retry Backoff​

If an authentication request fails, applications should not retry immediately in rapid succession. Instead, implement an exponential backoff strategy to prevent triggering security protections.

Avoid Parallel Authentication Requests​

Multiple systems or threads should not attempt authentication simultaneously using the same credentials.

  1. Centralize token retrieval in one component
  2. Share the retrieved token across services
  3. Ensure only one token request is made at a time per credential set