Authentication

The entity User or ApiClient can authenticate against the Madek-API. The API supports two methods for authentication: "Basic Auth" and a "Session Token".

The root-resource will never require authentication. Other resources might require authentication and some query parameters may only make sense with authentication.

An instance of the Madek API can be configured such that all resources besides the root-resource require authentication.

We recommend to always access the API with authentication.

Authentication Methods

Http Basic

This authentication method is primarily meant to be used for ApiClients.

The "Http Basic" authentication method is commonly used and well documented. See Wikipedia: Basic access authentication or for an informal introduction or the official RFC2617.

It is based on providing a username and a password. It is thus not compatible with third party authentication methods like SWITCHaai or OAuth.

It is currently possible to use an persisted login (as the username) and password of an User. This feature will likely be removed in the future¹. Users should use the more secure "Session Token" to authenticate against the API.

Session Token

This authentication method is primarily meant to be used for Users.

A "Session Token" provides access to the API for a limited timespan and potentially other restrictions. "Session Tokens" are submitted as the value of the cookie madek-session. A session token can be retrieved via the path /my/session-token after the User has signed in. This is preferred over extracting it from the current cookie. The "normal user interface" creates such an cookie and it is therefore possible to transparently use the API-Browser with authentication once singed in.