Integrating matterial into your app or website can begin as soon as you create a matterial instance, requiring the following steps:

• Sign up with matterial and create your new app instance - it’s free!
• We recommend to invite a dedicated user used by the API, for example a user named api, website or similar.
• Now you can check out our sample clients which will give you a quick start on how to use the actual REST api.

Congrats! Read on to begin integrating matterial.

Overview of a typical API interaction

Instances

The term instance (in the API documentation the term data source is used) refers to a matterial environment containing documents, users and all other matterial data.
Since it is possible, that one user owns multiple instances, you have to specify the desired instance to work with in a separate request and the server will answer with a redirect to the actual server hosting your instance (which might be the same that you sent your login request to).

Application URL

In the documentation the urls are specified like this: <application-url>/api/logon...
The default <application-url> of the matterial SaaS site consists of the host https://my.matterial.com and the suffix mtr-backend. So the default <application-url> is https://my.matterial.com/mtr-backend.

Standard authentication procedure

Matterial uses a cookie JSESSIONID to handle authentication. The cookie is set after a successful authentication request and must be added in each subsequent request.

The standard procedure looks as follows:

• Send a POST to <application-url>/api/logon/prelogin with user id and password as payload (json or XML). If successfully authenticated, it returns all instances (data sources) of the current logged on user as json or xml. Also the cookie having the id JSESSION is set.
• Using the instance id of one of the previously returned data sources, send a GET to <application-url>/api/logon/login/<instanceId> in order to get a redirect to the actual server hosting your instance.
• Send all subsequent request to the server you have been redirected to.
  Please Note
  The redirect url points to the html UI of the matterial instance - for example https://host2.matterial.com/matterial. For the REST API, only use the host part of the redirect url.

Now you can start using the rest of the API.
App - Development: Rest Interface