matterial

Zurück zur Übersicht » REST - Logon

REST - Logon

REST-Interface

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

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Logon

Produces

application/json
application/xml

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

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

Produces

application/json
application/xml

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

Permission
Login

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


Login

Login with username / password.

URL
POST <application-url>/api/logon

Query parameter

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Logon

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

Permission
-

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


Check username and password only

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

Permission
systemAccountRequired

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


Impersonate

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

Permission
ADMINISTRATE_ALL, systemAccountRequired

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


Change client

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

Path parameter

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

Permission
Login

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


Change password

Changing the password of current user. Leave passwordNew and passwordNew2 empty (null) to unset 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

Permission
Login, demoAccountForbidden

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


Logout

URL
DELETE <application-url>/api/logon

Produces

text/plain

Boolean - loggedOut

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

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

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

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

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

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

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

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

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

Permission
ADMINISTRATE_ALL

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