Recommendations of the JSON API standard

Our LEVERADE API adheres to the standard JSON API, which specifies a set of rules about how data is sent and received when communicating with the API.

Very detailed information about this standard can be found here.

How to access the API endpoints via OAuth 2

Authorizing access with OAuth 2

Our API follows the standard protocol for authorizing OAuth 2, whose documentation can be found here. More concretely, we recommend that you use the Authorization code grant flow that OAuth 2 specifies.

Please remember that in OAuth 2 we consider these entities, and we will refer to them properly in this article:

  • Client: The application that wants to make requests to the API.
  • User: The person who gives the client access to its data (or some portion of it).
  • Resource Server: The server that serves the requests to the API and returns its responses.

Getting the client credentials

In order to start the process of requesting an access_token (and make requests to the resource server with it), some client credentials are needed. These credentials can be requested sending an email to api@leverade.com, with the following data:

  • Email of the LEVERADE account.
  • The client’s name.
  • The desired URI where the user will be redirected after the authorization (to request the access_token).

If the request is granted, a response email will be sent with the following data:

  • The ID client.
  • The client secret.

Please note that the client secret should never be exposed to the public. It’s a private key.

Using client credentials to get the access token

In the first place, the application will have to show a window with the following link, so the the user can login and authorize access to the client. This HTTPS operation is done using the GET method, where the shown parameters are in the query string:

https://beta.leverade.com/oauth/authorize?client_id=client_id&redirect_uri=redirect_uri&response_type=code

Once this step is completed, LEVERADE will redirect the user to the desired redirection URI given by the client. In this URI, the client will have to take and process the request_token parameter. The redirection URI used by LEVERADE will end up looking like this:

redirect_uri?code=request_token

In order to get the access_token, the client will have to make a HTTPS POST request to the following URI, where shown parameters must be put in the body of the request (and not the query string)

Here is a example of this last request using curl:

curl -X POST -d "client_id=client_id&redirect_uri=redirect_uri&client_secret=client_secret&grant_type=authorization_code&code=request_token" https://api.leverade.com/oauth/token

LEVERADE will answer this request with the following JSON object, which the application should store:

{
    "access_token": "access_token",
    "expires_in": expiration_date,
    "refresh_token": "refresh_token",
    "token_type": "Bearer"
}

This access_token lets the client make requests to the API with the user’s permission.

Headers to include when making requests to the API

If a client wants to use an access_token, the following header must be included in all requests:

Authorization: Bearer access_token

Additionally, although optional, it’s recommended to point out in what formats the data will be sent and received. This can be accomplished including the following headers:

  • Accept: application/vnd.api+json
  • Content-Type: application/vnd.api+json

This format is similar to application/json, but it follows the specification of JSON+API, whose detailed information can be found here.

General diagram of how event resources relate

Relational diagram of event competitions