How to use the API

The below information is a high-level overview of how to use the Auth API v2.

Prerequisite:

A valid admin user must be set up in Enable’s Identity and Access Management (IAM) platform Okta to be able to view the application that has access to generate access tokens. If you do not have an Okta administrators account, please contact Enable. In Okta, you will find an API application for each organisation brand with a set of credentials to use in the Auth v2 API. This application must first be activated by the Enable administrator and have scopes assigned for your use.

1. Login in Okta https://enable.okta.com/
2. Go to the admin area (this is a button in the top right corner of the page, if you do not see this, you likely do not have admin access).
3. Go to the Application section through the navigation panel on the left of the screen and select the application you want to generate an authentication token for (eg. Production or Sandbox)
   • If the status shows as Inactive, ask Enable Admin to activate the application.
   • If an application is being activated for the first time, ask Enable Admin to assign scopes for APIs you want to use.
   • If you need access to additional/different APIs, ask Enable Admin to assign those additional scopes.
   • The required scopes for applications and their level of access can be found in the documentation for each API.
4. Retrieve the Client ID and Secret from the application page.
   • If you need to reset the Secret, send a request to the Enable Admin who can rotate these credentials for you. (Unfortunately due to a limitation in Okta, Enable cannot currently grant access to organisation admins to perform this action).

Once you have fetched your credentials, the next step is to generate an access token through the Auth v2 API.

Steps:

1. Fetch your credentials from Okta (Explained above).
2. Base64 Encode your Okta Client ID and Secret as "Client ID:Client Secret".
3. Send a Post request to the /token endpoint with the required scopes.
4. If successful, the response will contain the access token. This is the authorisation token required to access other Enable APIs.  

Below is a python example which shows how to generate an access token from the Auth v2 API.

import base64
import requests
import json
import uuid

token = ""

# step 1, retrieve your client id and secret from Enable Okta
client_id = "{your client id}"
client_secret = "{your secret}"

# step 2, build the request head using base64 encoder

token = f"{client_id}:{client_secret}"
encoded_token = str(base64.b64encode(token.encode('utf-8')).decode('utf-8'))
headers = {
    "AUTHORIZATION": f"Basic {encoded_token}",
    "Content-Type": "application/json",
    "x-transaction-id": str(uuid.uuid4())
}

# step 3, post the auth api v2 request to the /token endpoint with at least 1 scope
# Make sure to update the scope provided below with a scope you have access to!

sandbox_host = "https://staging.apis.enable.net.nz/auth"
version = "v2"
url = f"{sandbox_host}/{version}/token"
response = requests.post(
    url,
    headers=headers,
    data=json.dumps({
        "scopes": [
            "RSPCode.{RSP_shortcode}" 
        ]
    })
)
         
# step 4 check the returned result. If successful, the response will contain the 
# access token.

res = json.loads(response.text)
print(res)

Tips:

• When Base64 Encoding the Okta Client ID and Client Secret, make sure to include the colon ":"
• The access token will be reset every 12 hours. To allow continuous access to Enable APIs, ensure a new token is retrieved before the previous token expires.

The table below outlines how different aspects of the Auth API operate, and how each can be used.

Note regarding versions:

The v1 is the legacy Auth API and will work for 6 months after v2 release.

The v2 is for the new Auth API, please migrate to using it as soon as possible.