Authenticate#
Methods#
POST#
Accepts form data or JSON to authenticate a user’s credentials.
POST /authenticate
The payload, whether form data or JSON, should have the following attributes:
Attribute |
Value Type |
Description |
---|---|---|
|
string |
The username of the user. |
|
string |
The user’s password. |
If the credentials are valid, a JSON web token (JWT) is returned. This token is returned either as a token
cookie or in a JSON object with a token
attribute, depending on whether the original_url parameter was sent with the request.
To use a token returned in a JSON object to authorise a request, set the Authorization
header value to Bearer {your token}
, where {your token}
should be replaced with the value of token
in the response from /authenticate
.
If the user cannot be authenticated because the username or password are incorrect then a redirect response will be returned, pointing to the value of the Referer
header in the request.
The response will be a 400 error if either attribute is missing or a value is of an invalid type.
original_url#
The original_url
parameter is typically used when authenticating the user from form data sent from a web page. Its value is set to the path of the page from where the user was redirected to the login page, and its where the response from /authenticate
will redirect the browser upon successful authentication. It can be sent as a cookie or a query parameter with the /authenticate
request. Its presence in the request will result in the response from /authenticate
setting a cookie with the JWT, rather than returning a JSON object containing the JWT.
For example, if an unauthenticated or unauthorised user attempts to access the configuration page of the built-in web interface, they would try to navigate to /default/config.lsp
but the controller’s web server would redirect them to default/login.lsp
and set the original_url
cookie to /default/config.lsp
.
In a custom web interface using .webconfig
files to configure access control, the original_url
cookie is automatically set by the web server when redirecting to the login page (which may be a custom login page) when the user attempts to access a restricted page for which they are not authorised.
In both cases, when the login page submits a request to /authenticate
, the original_url
cookie will be sent automatically by the browser. A successful response will redirect to the value of original_url
and store a token
cookie in the browser with the user’s JWT.