Authentication and Authorization

  3 min read  

Both OAuth 2 and Token based API authentication/authorization is supported. For maximum security, it is recommend to use OAuth 2 authentication/authorization for your API when ever possible. The OAuth 2 authorization code grant type, or authorization code flow is supported

OAuth 2.0 and API Token

You can create OAuth 2 secret or API token by following below steps. For OAuth 2, use App/Device ID as the Client ID.

• Navigate to My Apps/Devices on the left hand side menu.
• Select/double click on your App/Device card from the list. If you do not have any App/Device created already refer Apps or Devices guide on how to create a Apps or Devices digital representation.
• On the App/Device definition page, select the API Authorizations tab.
• You can create either OAuth 2 secret or a API Token by clicking on the lock button in each section.
• Now copy the OAuth secret or the API Token and use it for your API authentication.

Obtaining OAuth Tokens

Use authorization code flow to obtain a OAuth 2 authorization code. When obtaining token you can send client credentials either in header or body. Both method are supported. Using authorization code, OAuth 2 secret and Client ID …etc you can obtain a OAuth 2 token.

Token expires in 2 hours, so use the refresh token to renew the token. Once OAuth 2 token is obtained use the token as Bearer authentication scheme in Authorization header.

In case if you require to use Authorization header for your custom API for downstream authentication, use x-rpz-auth header instead for Bearer authentication scheme.

e.g. Your HTTP header would looks like this:

...
Authorization: Bearer  OAUTH_TOKEN
...

Creating and Using API Token

If your App/Device (client) is a backend or is a server-side, then use HTTP Basic authentication scheme for authentication. So you must use the App/Device ID as username and specify the API Token as the password in the Authorization header.

In case your App is a frontend only app e.g. static webapp, then token can be used in the URL query string with the token as a parameter name e.g. https://...?token=YOUR_API_TOKEN. However, this method is not encouraged.

In HTTP Basic authentication you need to use username and password separated by a single colon (":") character and the whole string needs to be Base64 encoded.

In case if you require to use Authorization header for your custom API for downstream authentication, use x-rpz-auth header instead for Basic authentication scheme.

e.g. Your HTTP header would looks like this:

...
Authorization: Basic  Base64( APP_DEVICE_ID:YOUR_API_TOKEN )
...

where Base64() is a a base64 encoding function in your language/library

All connections must be established with TLS >= 1.2 to avoid compromising your token & data. When using SDK TLS is automatically handled by the implementation.

Authorization

If your App/Device has a separate backend/server, it is highly recommended to whitelist only your Domain or IP address(s) in the API Authorization tab of your App/Device configuration (navigate via My App & Device menu)