Authentication

Authentication against the API is performed using the credentials of a normal Monitor ERP user. This allows the API to interact like a normal user against the system with change-track logging, etc.

New (v25.8+): Passwordless browser-based login via OpenID Connect is supported. See OpenID Connect (OIDC) Login for the OIDC flow (Authorization Code with PKCE) and prerequisites if you prefer delegating authentication to Microsoft Entra ID / an external Identity Provider.

Request

Below is an example authentication request.

POST /{languageCode}/{companyNumber}/login HTTP/1.1
Host: {host}:8001
Content-Type: application/json
Cache-Control: no-cache
Accept: application/json

{
  "Username": "EXAMPLE",
  "Password": "passwd",
  "ForceRelogin": true
}

ForceRelogin

Setting the ForceRelogin parameter to true will close all other active sessions for the given user.

Response

There are two types of 200 OK responses to an authentication request to /login. You will need to parse the response body and look at the MfaToken property to determine if a multi-factor authentication is required for the user.

  • If the MfaToken property is null, then the user don't need to perform a multi-factor authentication according to Success.
  • If the MfaToken property contains a string, then the user will need to follow the steps described in Multi-factor authentication.

Success

Below is an example response received after a successful login attempt.

HTTP/1.1 200 OK
Content-Type: application/json
...
X-Monitor-SessionId: CfDJ8AAAAAAAAAAAAAAAAAAAAAC0MJtDu3SHpztOTLQjhGQeCOTbMKuJD6zKUkrdGqXHymVjJ2thF4yF_QuU5_xjYXtZT3IKX4O3__3vsG8

{
  "$id": "1",
  "SessionId": "d497f3b1-a91a-4436-9ccd-45dc8c2eba79",
  "MfaToken": null
}

The response body of the request should be ignored as it only contains some serializer metadata. The important part of the response is the X-Monitor-SessionId header, put the value of the header aside as this is the identifier you will use to authenticate your requests with.

To authenticate a request with your session id, simply attach a X-Monitor-SessionId header to your request with the value of the identifier that you pulled from the authentication response.

Failure

In case of a login failure, the responses would look as follows.

HTTP/1.1 403 Forbidden
Content-Type: application/json

"User login failed"

This typically occurs if the username or password is invalid.

HTTP/1.1 403 Forbidden
Content-Type: application/json

"MFA required but user setup missing"

This typically occurs if the user is blocked by not having setup a multi-factor authentication device. See Multi-factor authentication for more information on how to setup an multi-factor authentication device.

Remarks

Authentication with the API is valid per-company which means that you cannot carry over your authenticated session from one company to another.

You may only have one active session per user at a time.