OAuth2 Authentication Guidelines

1. Introduction

HORISEN APIs use the OAuth 2.0 protocol for authentication. It supports common OAuth 2.0 scenarios, such as machine-to-API or user-to-API access.

2. OAuth2 Authentication

To set up and run your app, follow these steps.

2.1 Register Application and Obtain Credentials

Provide your app information to our support team: name, redirect URL (for client-side applications), and IP address(es) from which your app will access our APIs (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 responsible for its own data after being granted 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 in a cron job performing maintenance tasks over an API. Another example is when a client makes requests to an API that don't require a user 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: Replace {platform_domain} with your platform domain. {separator} can be either . or -, depending on your platform configuration.

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 API authorization codes routed through the user-agent.

The following steps describe the authorization code flow.

2.2.2.1 Authorization Code Link

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). They will be prompted by the service to authorize or deny the application's 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 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 that 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"

1. Introduction​

2. OAuth2 Authentication​

2.1 Register Application and Obtain Credentials​

2.2 Implement Authentication to Obtain Access Token​

2.2.1 Client Credentials Grant​

2.2.2 Authorization Code Grant​

2.2.2.1 Authorization Code Link​

2.2.2.2 User Authorizes Application​

2.2.2.3 Application Receives Authorization Code​

2.2.2.4 Application Requests Access Token​

3. API Call Example​