API Documentation

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

  • 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.

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

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

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

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

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

  • 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

Contact sales