API authentication
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 thecurl
calls is required as they allow to re-use the same server session (identified by theJSESSIONID
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.
- default (ROOT deployement)
- non ROOT deployement
For a default root deployement, the API endpoint is /api
BASE_URL="http[s]://<host[:<port>]>/api"
For a non ROOT deployement, the API endpoint is /myapp/api
BASE_URL="http[s]://<host[:<port>]>/myapp/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.
- HTTP Basic auth
- GET (not recommended)
- POST (not recommended)
TOKEN=$(curl -u <login>[:<password>] "$BASE_URL/login")
Information exposure through query strings in url is a very bad practice, please use HTTP Basic Auth instead.
TOKEN=$(curl "$BASE_URL/login?username=<login>&password=<password>")
TOKEN=$(curl --form "username=<login>" --form "password=<password>" "$BASE_URL/login")
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.
- Accept header (v5.2.39+)
- URL Parameter
Set the Accept
header to application/json
:
curl -u <login>[:<password>] -H "Accept: application/json" "$BASE_URL/login"
Set the optional parameter ?format=json
or ?_json=true
or _output=json
curl -u <login>[:<password>] "$BASE_URL/login?format=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>"
}
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/..."
After the server session times out the response will be an HTTP code 401
.
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 theUSERTOKENS_URL_PARAM
system parameter.
Different APIs are available under /api
and they are documented seperately :
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"