Ondilo authentication service reference

General considerations

This document describes the Ondilo authentication service. It is intended to help on authenticating the users within Ondilo system.

Headers

The Ondilo authentication service uses UTF-8 as the response encoding and supports HTTP-level compression. Requests should have the following headers:

Accept: application/json
Accept-Charset: utf-8
Accept-Encoding : gzip-deflate
Content-type: application/json

HTTP status codes

The Ondilo authentication service uses the following set of HTTP response status codes:

Status Description
200 The request was successful, no error was encountered.
400 There is a problem with some data sent in the request. An error response body shall clarify the issue.
401 The data sent is invalid.
404 You are trying to reach a page that doesn't exist.
500 An error in the Ondilo authentication application logic has been detected. An error response body shall clarify the issue.
503 The Ondilo authentication is not currently available. You should try again later.

Response body format

The Ondilo authentication service provides response bodies as JSON objects. Format of the objects depend of the endpoint called.

{
    // The data contained here depends on the endpoint,
    // but it is either an object or an array
}

Authentication

The Ondilo authentication service ensures user authentication for the Ondilo customer API. This means that your application must authenticate against this service before it can call any endpoint on the API.

Authentication flow

The Ondilo authentication uses OAuth2 authentication, including the use of refresh tokens.

The Ondilo customer API uses access tokens for authentication and as a source of identity. A single access token always refers to a single user account.

Access tokens have a lifetime of one hour, while refresh tokens are non-expiring.

Authorization

To begin authentication, your application must redirect the user to our authorization endpoint with the following request:

Request

Method GET
URL https://interop.ondilo.com/oauth2/authorize

Parameters

client_id customer_api
response_type code
redirect_uri The Ondilo authorization service will redirect the user back to your application whether the user successfully authorized your application or denied access.
scope api
state An anti-forgery token provided by your application.

Example

https://interop.ondilo.com/oauth2/authorize?client_id=customer_api&response_type=code&redirect_uri=https%3A%2F%2Fyour.app.url%2Fauthorize&scope=api&state=c0d45ff768a0

Authorization grant

The authorization endpoint will display a form requiring the user to enter the email and password of his Ondilo account. By clicking on the Authorize button, the user grants your application access to his data.

Redirect

Once the user has authorized your application to connect to his account, he will be directed to the redirect URI provided in the request with an authorization code that must be exchanged for a bearer token in the next step.

https://your.app.url/authorize?code=78329a3893546bb42ed&state=c0d45ff768a0

Denial

If the user denies the authorization for your application to access his data, he will be directed to the redirect URI provided in the request with an error.

https://your.app.url/authorize?error=access_denied

Token exchange

Once it has received an authorization code for the user, your application must issue immediately a POST request to our token endpoint in order to exchange the authorization code for an access token.

Request

Method POST
URL https://interop.ondilo.com/oauth2/token

Parameters

code The authorization code that has been generated in the previous step by our authorization endpoint.
grant_type authorization_code
client_id customer_api
redirect_uri The same URI that the one provided in the previous step.

Example

POST /oauth2/token
Host: interop.ondilo.com
Content-Type: application/x-www-form-urlencoded

code=78329a3893546bb42ed&grant_type=authorization_code&client_id=customer_api&redirect_uri=https%3A%2F%2Fyour.app.url%2Fauthorize

Response

If the authorization code is invalid (unknown or outdated), response will have a 400 status code with an error message in the body. In the other case, respond with a 200 status code and the following body:

HTTP/1.1 200 OK
Content-Type: application/json; charset: utf-8

{
    "access_token": "d81bf6c859e581893f10a190e4739b35c2fb5259",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "api",
    "refresh_token": "19d134b486b5416147fd7df9d3fcb9d25ff904fa"
}

Refresh tokens

An access token has a lifetime of 1 hour. Once it has expired, a call to any endpoint of the Ondilo Customer API will end with a 401 status code. Your application must then make a POST request to our token endpoint and use the refresh token returned in the token exchange step.

Request

Method POST
URL https://interop.ondilo.com/oauth2/token

Parameters

refresh_token The refresh token retrieved in the previous step of the Authentication Flow.
grant_type refresh_token
client_id customer_api

Example

POST /oauth2/token
Host: interop.ondilo.com
Content-Type: application/x-www-form-urlencoded

refresh_token=19d134b486b5416147fd7df9d3fcb9d25ff904fa&grant_type=refresh_token&client_id=customer_api

Response

If the refresh token is invalid (unknown or outdated), response will have a 400 status code with an error message in the body. In the other case, respond with a 200 status code and the following body:

HTTP/1.1 200 OK
Content-Type: application/json; charset: utf-8

{
    "access_token": "4fc86e46a11abbb3914b90af3e21f2858f3376f5",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "api"
}