Skip to main content

API authentication

warning

This document only applies to the API endpoint.

This document does not apply to:

  • legacy webservices endpoint (that uses authentication methods configured at the server configuration level)
  • the I/O endpoint
  • the GIT endpoint

The example use the curl command line tool (that can easily be transposed to any other HTTP client tool or API).

Note: in version 3.x adding -b cookies.txt -c cookies.txt as arguments of the curl calls is required as they allow to re-use the same server session (identified by the JSESSIONID cookie). In versions 4.0+ a technical session is used to avoid taking care of the session cookie.

API Base URL​

In all following examples, $BASE_URL is used to represent the app's API endpoint.

For a default root deployment, the API endpoint is /api

BASE_URL="http[s]://<host[:<port>]>/api"

Login​

To get an access token, a first call to the login service ($BASE_URL/login[<optional parameter(s)>]) is needed. As this login service is only dedicated to webservices, no interactive login/password entry mechanisms is available. Whatever method is used to retrieve the access token, it must be used for subsequent service calls. In all following examples, $TOKEN is used to represent the token.

TOKEN=$(curl -u <login>[:<password>] "$BASE_URL/login")
info

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

Plain text Response​

The default response is the access token as plain text.

Redirect URI Response​

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.

curl -u <login>[:<password>] "$BASE_URL/login?redirect_uri=..."

JSON Response​

It is possible to get a JSON formatted response instead of the plaintext default.

Set the Accept header to application/json:

curl -u <login>[:<password>] -H "Accept: application/json" "$BASE_URL/login"
{
	"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>"
}

Oauth2 Response​

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
}

Service calls​

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

curl -H "X-Simplicite-Authorization: Bearer $TOKEN" "$BASE_URL/..."
info

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

info

If for som odd reason you can't set the X-Simplicite-Authorization header you have two other options:

  • Use the default Authorization header with the same content (Bearer <token>) but in some contexts (like in a web browser) this can be in conflict with other mechanisms using this header
  • Add _x_simplicite_autorization_=<token> as URL parameter. As of version 5.1 (and backported in version 4.0) it is possible to customize the name of this URL parameter using the USERTOKENS_URL_PARAM system parameter.

Different APIs are available under /api and they are documented separately:

Logout​

To explicitly log out (before the server session times out) the logout service can be called on $BASE_URL/logout

curl  -H "X-Simplicite-Authorization: Bearer <token>" "$BASE_URL/logout"
Last updated on