Services authentication

This document applies only to the API endpoint deployed as of version 3.0 MAINTENANCE 20 in the main webapp.

Note: This document does not apply to legacy webservices endpoint (that uses authentication methods configured at the server configuration level) nor to the I/O and Git endpoints.

For an application named myapp the base URL of the API endpoint, noted <base URL> in the rest of the document, is:

http[s]://<host[:<port>]>/myapp/api

For a root deployment this base URL is:

http[s]://<host[:<port>]>/api

The calls examples are given using the curl command line tool (that can easily be transposed to any other HTTP client tool or API).

Note: the -b cookies.txt -c cookies.txt parameters of the curl calls bellow are required as they allow to use the same server session (identified by the JSESSIONID cookie)._

Login

A first call to the login service is needed to get an access token:

<base URL>/login[<optional parameter(s)>]

The default response is the access token as plain text.

If the optional parameter redirect_uri=<redirect URI> is set, the access token <token> is added to this URI as the access_token GET parameter and the response is an HTTP redirect to this URI.

As of version 3.1 MAINTENANCE 01 it is possible to get a JSON formatted response by setting the optional parameter ?_json=true (or _output=json):

{
    "authtoken": "<auth token, e.g. eVXGhFz5ovn1yCRU9N2U4rO7Chv9aiphSjUK5njA4clCSHXy5t>",
    "sessionid": "<server session ID, e.g. FD22A705AE469A414333BD0DE6A0222D>",
    "login": "<user login>",
    "firstname": "<user first name>",
    "lastname": "<user last name>",
    "lang": <user language code, e.g. ENU>"
}

As of version 3.1 MAINTENANCE 07 it is also possible to get a OAuth2 style response by setting the optional parameter ?_oauth2=true (or _output=oauth2). Note that in this case you must use HTTPS.

{
    "access_token": "<auth token, e.g. eVXGhFz5ovn1yCRU9N2U4rO7Chv9aiphSjUK5njA4clCSHXy5t>",
    "token_type": "bearer",
    "expires_in": <server session timeout, e.g. 300>,
    "scope": null
}

In any cases the access token<token> is to be used for subsequent calls (see below).

The credentials (login and password) can be passed either:

As a HTTP basic authentication header (the curl call bellow uses the standard header but the custom header can also be used):

curl -b cookies.txt -c cookies.txt -u <login>[:<password>] "<base URL>/login"

Or as plain URL parameters of a GET request (not recommended):

curl -b cookies.txt -c cookies.txt "<base URL>/login?username=<login>&password=<password>"

Or as plain URL parameters of a POST request (not recommended):

curl -b cookies.txt -c cookies.txt --form "username=<login>" --form "password=<password>" "<base URL>/login"

As this login service is only dedicated to webservices, no interactive login/password entry mechanisms is available.

Note: If the credentials are incomplete or not accepted for any reason the response will be an HTTP code 401.

Use access token in service calls

All subsequent calls must pass the access token in the custom X-Simplicite-Authorization header:

curl -b cookies.txt -c cookies.txt -H "X-Simplicite-Authorization: Bearer <token>" "<base URL>/..."

Note: After the server session times out the response will be an HTTP code 401.

Logout

To explicitly log out (before the server session times out) the logout service can be called:

<base URL>/logout

A typical call is:

curl  -b cookies.txt -c cookies.txt -H "X-Simplicite-Authorization: Bearer <token>" "<base URL>/logout"