Authentication
Access to the REST API is restricted to authenticated users. Requests may be authenticated by:
-
An ASP.NET Forms Authentication ticket set via a cookie.
-
A custom header
X-Auth-Tokencontaining the token retrieved by using the Authenticate resource. -
A new generated token created by using the Create token or Create token using OAuth.
It is recommended to create a token following the OAuth method.
Cookies and tokens are used to make sure the user does not have to go through the entire authentication process every time a request is being made.
Cookies are primarily used by browsers. The client fills in his credentials using a web based form and the browser then sends these credentials to the server. If the credentials are valid, the server returns a message to the browser telling it to create a cookie with a unique session ID that identifies the user. This cookie is included in every request the browser makes to the server, enabling the server to identify the user that made the request.
A non-browser that communicates with the API (ie. another API) does not know how to deal with cookies and thus needs to authenticate using a different method. The main principle of authenticating stays the same however. The third party first needs to provide the credentials to the server. The server will check the credentials and if they are valid it will respond with a token that is unique for every user. This token works exactly the same as the session ID that is being stored in the cookie. With every request this access token needs to be included in the X-Auth-Token header.
Unlike cookies the access token does not expire unless it is revoked manually.