OAuth2 Authentication Guidelines

OAuth2 Authentication Guidelines

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.

Follow the below steps to get up and running:

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 accesses our APIs (only for server-side applications). In return, you will be given client_id, client_secret which must be stored securely on your server.

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. Authorization code grant - should be used when a user is present to interact (login and approve) app access. This is similar to how Google, Facebook social login and API access work.
Client credentials grant - suitable for machine-to-machine authentication, for example for use in a cron job which is performing maintenance tasks over an API. Another example would be a client making requests to an API that don't require user's interaction.

3. Call

POST/oauth2/access-token
content-type is application/x-www-form-urlencoded.Up

Having a valid access token, you are ready to access API endpoints of your choice. Each access token has an expiration time, so you need to obtain a new one if the existing one is expired.

Here's a CURL example of how an access token can be obtained (please replace CLIENT_ID and CLIENT_SECRET with the ones you received from Support or you created in the Security App):

curl https://api.horisen.pro/oauth2/access-token -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'

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}