REST - Logon

REST-Interface

Back to overview

Login procedure

The login procedure consists of three steps:

  1. PreLogin
  2. Read cookie
  3. Redirect to LoginServer

Prelogin
The Prelogin API checks user name and password and determines the instances that the user has access to. It returns a list of instances (DataSources).

Cookie
After successful call of the PreLogin API, a cookie with the ID JSESSIONID is returned. You need to get the cookie and set it in each subsequent requests.

Redirect to LoginServer
The Redirect to LoginServer API gets the instance id as a parameter and returns a redirect to the actual server hosting the web UI of the respective instance (default: https://my.matterial.com/matterial).

Note
In case you are not in an interactive Browser UI where the Browser will automatically be redirected to the web user interface, you might need to strip the base path from the redirected URL and use it for all subsequent requests (which means basically to remove /matterial from the URL).

PreLogin

Checks user/password including active instance. Returns all available instances (datasources) for current user.
URL
POST <application-url>/api/logon/prelogin

Query parameter

  • rememberMe
    possible: true, false
    default: false
    Remember the user on success (cookie + tempKey)
  • overwriteServerUrl
    Special option for webdev:
    possibility to overwrite the serverUrl of the datasource.
    Format: http://localhost:8080

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Logon

Produces

application/json
application/xml

List<com.matterial.mtr.api.object.DataSource>

  • 200 OK
  • 401 UNAUTHORIZED

Permission
-

Sample
POST http://localhost:8080/mtr-backend/api/logon/prelogin


Redirect to LoginServer

Redirects to the respective server hosting the instance. This API is called after prelogin / preChangeInstance with instance-id as parameter.

This API does only work after a successful preLogin- or preChangeInstance-call, because these prepare a LoginToken for the user.
URL
GET <application-url>/api/logon/login/<instanceId>

Produces

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/logon/login/2


PreChangeInstance

Gets all available datasources for current user.
URL
PUT <application-url>/api/logon/prechangeinstance

Query parameter

  • overwriteServerUrl
    Special option for webdev:
    possibility to overwrite the serverUrl of the datasource.
    Format: http://localhost:8080

Produces

application/json
application/xml

List<com.matterial.mtr.api.object.DataSource>

  • 200 OK
  • 401 UNAUTHORIZED

Permission
Login

Sample
PUT http://localhost:8080/mtr-backend/api/logon/prechangeinstance


Login

Login with username / password.

Attention:
Won't work on multiserver-installation.
Use PreLogin-api instead!

URL
POST <application-url>/api/logon

Query parameter

  • rememberMe
    possible: true, false
    default: false
    Remember the user on success (cookie + tempKey)

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Logon

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 401 UNAUTHORIZED

Permission
-

Sample
POST http://localhost:8080/mtr-backend/api/logon


Check username and password only

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

Only check user/password against database.
Returns true, if person with given credentials was found.
No active-instance-check.
Only allowed for “system”-account!
URL
POST <application-url>/api/logon/check

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Logon

Produces

text/plain

boolean - passwordOk

  • 200 OK
  • 401 UNAUTHORIZED

Permission
systemAccountRequired

Sample
POST http://localhost:8080/mtr-backend/api/logon/check


Impersonate

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

URL
POST <application-url>/api/logon/impersonate

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Logon

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 401 UNAUTHORIZED

Permission
ADMINISTRATE_ALL, systemAccountRequired

Sample
POST http://localhost:8080/mtr-backend/api/logon/impersonate


Change client

Attention:
Having multiple clients is currently only supported by on-premises installations (private cloud).

URL
PUT <application-url>/api/logon/client/<clientId>

Path parameter

  • clientId

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 401 UNAUTHORIZED

Permission
Login

Sample
PUT http://localhost:8080/mtr-backend/api/logon/client/2


Change password

URL
PUT <application-url>/api/logon

Consumes

application/json
application/xml

com.matterial.mtr.api.object.PasswordContainer

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 400 BAS REQUEST

Permission
Login, demoAccountForbidden

Sample
PUT http://localhost:8080/mtr-backend/api/logon


Logout

URL
DELETE <application-url>/api/logon

Produces

text/plain

Boolean - loggedOut

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
-

Sample
DELETE http://localhost:8080/mtr-backend/api/logon


Logout via GET

Logout from the current session and redirects to ui.
URL
GET <application-url>/api/logon/logout

Produces

text/plain

Boolean - loggedOut

Permission
Login, twoFactorAuthNotRequired

Sample
GET http://localhost:8080/mtr-backend/api/logon/logout


Is logged-in

Always results in HTTP-Status OK (200) with additional answer “true/false”.
URL
GET <application-url>/api/logon

Produces

text/plain

Boolean - loggedIn

  • 200 OK

Permission
-

Sample
GET http://localhost:8080/mtr-backend/api/logon


Get LoginData

URL
GET <application-url>/api/logon/logindata

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 401 UNAUTHORIZED

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/logon/logindata


Activate DisableRightsCheck

Set disable rights check to true for this session and overwrites account-setting.
URL
PUT <application-url>/api/logon/disablerightscheck/activate

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
PUT http://localhost:8080/mtr-backend/api/logon/disablerightscheck/activate


Deactivate DisableRightsCheck

Set disable rights check to false for this session and overwrites account-setting.
URL
PUT <application-url>/api/logon/disablerightscheck/deactivate

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
PUT http://localhost:8080/mtr-backend/api/logon/disablerightscheck/deactivate


Reset DisableRightsCheck

Reset disable rights check for this session and reset to account-setting-value.
URL
PUT <application-url>/api/logon/disablerightscheck/reset

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
PUT http://localhost:8080/mtr-backend/api/logon/disablerightscheck/reset


Disable indexing of documents

Disable indexing of documents for the rest of this session.
URL
DELETE <application-url>/api/logon/index/document

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
DELETE http://localhost:8080/mtr-backend/api/logon/index/document


Reenable indexing of documents

(Re)enable indexing of documents for the rest of this session.
URL
PUT <application-url>/api/logon/index/document

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
PUT http://localhost:8080/mtr-backend/api/logon/index/document


Disable indexing of persons

Disable indexing of persons for the rest of this session.
URL
DELETE <application-url>/api/logon/index/person

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
DELETE http://localhost:8080/mtr-backend/api/logon/index/person


Reenable indexing of persons

(Re)enable indexing of persons for the rest of this session.
URL
PUT <application-url>/api/logon/index/person

Produces

text/plain

Integer 1 on success

  • 200 OK

Permission
ADMINISTRATE_ALL

Sample
PUT http://localhost:8080/mtr-backend/api/logon/index/person

×