API key

An API key identifies an API client, such as a web application or a server.

It is required for all interactions with the API, in particular to submit API requests. It is provided as a parameter apiKey in the URL query string, whatever the HTTP method used (GET or POST). If you use the JavaScript SDK, the API key is set at initialization and is automatically added to the request parameters.

An API key only grants a read-only access to public data (see the permissions section for details). The requesting user is considered as anonymous. If you want to manipulate private data, you need to add an access token in the URL query string.

Example

Without SDK

Consider you want to retrieve the public quiz with identifier PUBLIC_QUIZ_ID. To to this, send the request getQuiz with the parameter quizId=PUBLIC_QUIZ_ID and the required parameter apiKey :

GET https://api.jelevelamain.fr/getQuiz?quizId=PUBLIC_QUIZ_ID&apiKey=API_KEY

where API_KEY is your API key.

The API response will be Quiz containing public attributes only : 
{
    "id" : "PUBLIC_QUIZ_ID",
    "title" : string,
    "visibility" : "public",    
    "survey" : boolean,   
    "tags" : string[],
    "creationDate" : datetime,  
    "lastChangeDate" : datetime,    
    "author" : User,
    "nbQuestions" : unsigned integer,  
    "questions" : Question[],    
}

Using the JavaScript SDK

If you use the JavaScript SDK, simply instantiate the API interface with our API key and it will be added to the parameters of all API requests. These two lines of code perform the same HTTP request as above for you : 
var jllmAPI = new JllmAPI(API_KEY);
var quiz = jllmAPI.getQuiz({quizId : "PUBLIC_QUIZ_ID"});
Moreover, the variable quiz contains a ready-to-use JavaScript object modeling a Quiz and not a string (the JSON representation returned by the API is parsed for you).

How to get API keys

The API key manager allows you to consult, add or delete your API keys. You need to be logged in to use it; if not, click on the "Login" button at the right top of the page.

You can use this tool to create your first API key. Note that each API key is restricted to a specified host. You thus need to generate an API key for each server or web application that will use the API.

Access token

An access token allows performing operations on behalf of a Je Leve La Main user without filling a login form. It is valid for a limited time (typically one day).

It is optionally be provided as a parameter accessToken in the URL query string, whatever the HTTP method used (GET or POST). An UnauthorizedOperationException is thrown by the API if it is invalid or expired.

Providing an access token allows you to execute API requests as an authenticated user. In this context, you can manipulate your private data (related to your account) (see the permissions section for details).

Note that some API requests (that manipulates private user data only) cannot be executed as an anonymous user and thus requires an access token. See the request summary for details. For these requests, an UnauthorizedOperationException will be thrown by the API if no access token is provided.

Examples

Public quiz

Consider you want to retrieve the public quiz with identifier PUBLIC_QUIZ_ID including private attributes. To do this, execute the getQuiz request as an authenticated user, by adding your access token to the request parameters :

GET https://api.jelevelamain.fr/getQuiz?quizId=PUBLIC_QUIZ_ID&apiKey=API_KEY&accessToken=ACCESS_TOKEN

where API_KEY is your API key and ACCESS_TOKEN your access token.

The API response will be a Quiz containing public and private attributes : 
{
    "id" : "PUBLIC_QUIZ_ID",
    "title" : string,
    "visibility" : "public",    
    "survey" : boolean,   
    "tags" : string[],
    "creationDate" : datetime,  
    "lastChangeDate" : datetime,    
    "author" : User,
    "nbQuestions" : unsigned integer,  
    "questions" : Question[],    
    "imported" : boolean, 
    "favorite" : boolean
}
If you compare to the previous example (executed as anonymous user), you can see two additional attributes : "imported" and "favorite", which are specific to the requesting user.

Private quiz

Consider now you want to retrieve the private quiz with identifier PRIVATE_QUIZ_ID.

If you execute the getQuiz request as an anonymous user (without access token) :

GET https://api.jelevelamain.fr/getQuiz?quizId=PRIVATE_QUIZ_ID&apiKey=API_KEY

The API response will be a UnauthorizedOperationException : 
{
    "type" : "UnauthorizedOperationException",
    "message" : "Unauthorized operation: getQuiz (Access denied to quiz with id PRIVATE_QUIZ_ID)",
    "operation" : "getQuiz",    
    "reason" : "Access denied to quiz with id PRIVATE_QUIZ_ID"
}
If you execute the getQuiz request as an authenticated user (with access token) :

GET https://api.jelevelamain.fr/getQuiz?quizId=PRIVATE_QUIZ_ID&apiKey=API_KEY&accessToken=ACCESS_TOKEN

The API response will be a Quiz containing all attributes (public and private).

How to get access tokens

To get access tokens, you first need to get an API key as explained here.

Then, you can get an access token as follow :
  1. Go to the API authentication page :

    2. https://api.jelevelamain.fr/authentication/login.php?apiKey=API_KEY&redirectURL=REDIRECT_URL

    where API_KEY is your API key and REDIRECT_URL is the URL of the callback page. The host of REDIRECT_URL must match with the host associated to your API_KEY (IP or domain). Note that subdomains are allowed. If one of the required parameters is missing or invalid, an error message will be displayed.
  2. Fill the login form with your Je Leve La Main identifiers and validate.
  3. If the identifiers are correct, the authentication page will redirect to the callback page specified in REDIRECT_URL, with an extra parameter in the URL query string :

    4. accessToken=AccessTokenJSON

    where AccessTokenJSON is the (URL encoded) JSON representation of an object containing the access token : 
    {
    "token" : string,   
    "expiresIn" : unsigned integer
}
token is the string to add in the URL query string when submitting requests to the API. expiresIn is number of seconds until this access token expires. A typical value of expiresIn is 86400 seconds = 24 hours.

You have to retrieve and decode the access token and store it for future uses.

Important security note : Access token should NEVER be hard-coded into client-side code. Doing this would allow who inspect your code to access to your private data, and more generally perform operations on your behalf.

Example

Let API_KEY denote an API key generated for the host domain.com. Consider that the authentication page is accessed with the following URL :

https://api.jelevelamain.fr/authentication/login.php?apiKey=API_KEY&redirectURL=subdomain.mydomain.com/mypage

If a user submits valid Je Leve La Main identifiers, the authentication page redirects to :

subdomain.mydomain.com/mypage?accessToken={"token"%3A"ACCESS_TOKEN"%2CexpiresIn"%3A86400}

The URL-decoded value of accessToken is : 
{
    "token" : "ACCESS_TOKEN",   
    "expiresIn" : 86400
}

Easier : using the JavaScript SDK

The JavaScript SDK makes the authentication process easier: you do not have to explicitly load the authentication page, parse and store the access token. These few lines of code allow to simply manage the access token in a page : 
jllmAPI.storeAccessTokenFromUrl();

var accessToken = jllmAPI.getAccessToken();

if(accessToken === undefined){
    jllmAPI.authenticate(redirectUrl);
}
where jllmAPI is a JllmAPI instance and redirectUrl is the redirect URL added to the authentication page query string (optional).
  1. storeAccessTokenFromUrl() retrieves and parses the access token from the current URL if any. The retrieved access token is stored in the browser local storage and will be available if the user comes back later to the page.
  2. getAccessToken() gets a valid access token from the local storage if any. The function returns undefined is no access token is found or if the access token is expired.
  3. If no valid access token is available, authenticate() redirects to the authentication page to get a new access token. If no redirect URL is specified, current URL is used by default.
If you want to erase the access token stored in the local storage and force an authentication, call : 
jllmAPI.wipeAccessToken();

Even more easier : using the "Login button" plugin

If you use the Login button plugin, the JavaScript code to be inserted in your page is even more easier: 
jllmAPI.storeAccessTokenFromUrl();
jllmAPI.setLoginButton(buttonId);
where buttonId if the identifier of the Login Button in your page.

This button automatically changes its appearance and calls the methods authenticate() and wipeAccessToken() of the JavaScript SDK depending on the availability of a valid access token.

The redirect URL is implicitly the URL of the page where the button is included.

Permissions

Permission Anonymous user
(no access token provided)		 Authenticated user
(access token provided)
Get public quizzes Yes Yes
Get quizzes from an account Yes
Get user groups from an account Yes
Add quizzes to an account Yes
Get public user infos Yes Yes
Get known users private infos Yes
Get aggregated results Yes Yes
Get detailed results Yes