OAuth2 Authentication Guidelines

1. Introduction

HORISEN APIs use the OAuth 2.0 protocol for authentication. It supports common OAuth 2.0 scenarios such as those for machine2api or user2api access.

2. OAuth2 Authentication

In order to have your app set up and running, you need to make the following steps.

2.1 Register Application and Obtain Credentials

You need to provide your app information for our support team: name, redirect URL (only for client-side applications), IP address(es) from which your app will access our APIs (only for server-side applications).
In return, you will be given client_id and client_secret, which must be stored securely on your server.

Note: The client app is in charge for its own data after it's been given access to HORISEN APIs.

2.2 Implement Authentication to Obtain Access Token

There are two different flows and the one to be used depends on the nature of your app.

Client credentials grant - it is suitable for machine-to-machine authentication, for example for a use in a cron job which is performing maintenance tasks over an API. Another example would be when a client making requests to an API that don't require a user's interaction.

Authorization code grant - it should be used when a user is present to interact (login and approve) in an app access. This is similar to how Google, Facebook social login and API access work.

2.2.1 Client Credentials Grant

The client credentials grant type provides an application a way to access its own service account. Examples of when this might be useful include if an application wants to update its registered description or redirect URI, or access other data stored in its service account via the API.

The application requests an access token by sending its credentials, its client ID and client secret, to the authorization server. An example of POST request might look like the following:

curl https://accounts[separator][platform_domain]/oauth2/access-token -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'

Note: A domain is presented with placeholders as https://accounts{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

If the parameters are valid, and the call is made from the authorized IP address, the server will respond with JSON containing the access token:

{"access_token":"ACCESS_TOKEN","token_type":"Bearer","expires_in":604800}

2.2.2 Authorization Code Grant

The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user's web browser) and receiving an API authorization codes that are routed through the user-agent.

The following steps describe the authorization code flow.

First, the user is given an authorization code link that looks like the following:

https://accounts[separator][platform_domain]/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL

Here is an explanation of the link components:

Component Description
https://accounts[separator][platform_domain]/oauth2/authorize The OAuth2 server authorization endpoint.
response_type=code Specifies that your application is requesting an authorization code grant.
client_id The application's client ID.
redirect_uri Where the service redirects the user-agent after an authorization code is granted.
2.2.2.2 User Authorizes Application

When the user clicks the link, they must first log into the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access to their account.

2.2.2.3 Application Receives Authorization Code

If the user clicks "Authorize Application", the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code. The redirect would look something like this (assuming the application's redirect url is "https://example.com/callback"):

https://example.com/callback?code=AUTHORIZATION_CODE
2.2.2.4 Application Requests Access Token

If the authorization is valid, the API will send a response containing the access token (and optionally, a refresh token) to the application. The entire response will look something like this:

{"access_token":"ACCESS_TOKEN","token_type":"bearer","expires_in":604800,"refresh_token":"REFRESH_TOKEN"}

Now the application is authorized. It may use the token to access the user's account via the service API, limited to the scope of an access, until the token expires or is revoked. If a refresh token was issued, it may be used to request new access tokens if the original token has expired.

3. API Call Example

Having a valid access token, you are ready to access API endpoints of your choice.

Here's an example of a curl call which adds a new contact in your Business Messenger Customer Data Store.

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer ACCESS_TOKEN" -d "{
    \"list_uuid\": \"LIST_UUID\",
    \"first_name\": \"John\",
    \"last_name\": \"Smith\",
    \"mobile\": \"+12025550100\",
    \"email\": \"john@example.com\",
    \"address\": \"St One\",
    \"zip\": \"9000\",
    \"city\": \"NY\",
    \"country\": \"US\"
    }" "https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/cds/contacts"