REST - Logon
REST-Interface
Login procedure
The login procedure consists of three steps:
- PreLogin
- Read cookie
- 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
- 303 SEE OTHER - Location: URL to the web UI on server with the respective instance, i.e: https://my.matterial.com/matterial/
- 500 INTERNAL_SERVER_ERROR
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
- 303 SEE OTHER - Location: URL to UI, i.e: http://server:8080/matterial/
- 500 INTERNAL_SERVER_ERROR
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
