Authentication

To make API calls to the ESAPI you need a bearer token. Before you’re able to retrieve a bearer token you must first configure an Application and API Key.

Best Practice
Create an Application
Create an API Key
Request a bearer token
- Troubleshooting

Best Practice

You should create an Application for every client with direct access to the ESAPI. i.e. if you’re creating both a website and an app, that’s 2 applications. However, if you’ve created a backend webservice that interfaces with the ESAPI on behalf of your clients, that’s a single Application.

API Keys are recommended for use by a backend webservice, such that your API Key and Secret are completely hidden from users. Using an API Key in local Javascript, or an Android or iOS app puts the API Key and Secret at risk of being used by 3rd parties. We do not currently support IP restrictions on API Key usage.

Create an Application

Step 1

First, log into the Locatrix Account Management, and click the ☰ icon in the top left to reveal the drawer. Expand Applications, and then click Applications below it.

Step 1

Step 2

Next, on the Manage Applications page click Create New to start creating a new Application.

Step 2

Step 3

Enter the name of your Application
Set Allowed Grant Type to Resource Owner Password
All other fields should be left as-is

Then click Create.

Step 3

Step 4

Once the page loads you will be presented with your Application’s ID and Secret. You must save your secret now as it is not retrievable later. Close the modal once you’re sure you’ve saved the secret.

The below Application Secret is for illustration only. It is not valid for use.

Step 4

Create an API Key

Step 1

Next click the ☰ icon in the top left to reveal the drawer. Expand Applications, and then click API Keys below it.

Step 1

Step 2

Next, on the Manage your API Keys page click Create New to start creating a new API Key.

Step 2

Step 3

Select the Partner that the API Key has access to
Select Partner User as the role
Enter a name for the API Key

Then click Save.

Step 3

Step 4

Once the page loads you will be presented with your API Key and API Secret. You must save both your API Key and API Secret now as they’re not retrievable later. Close the modal once you’re sure you’ve saved the API Key and API Secret.

The below API Key and API Secret are for illustration only. They are not valid for use.

Step 4

Request a bearer token

You must request a bearer token by providing your Application ID/Secret and API Key/Secret to our authentication service.

URL

POST https://auth.locatrix.com/connect/token

Headers

Header	Required	Value
`Content-Type`	yes	`application/x-www-form-urlencoded`

Body

Body must be url encoded to match the application/x-www-form-urlencoded content type.

Form Parameters

Parameter	Value
`grant_type`	`password`
`scope`	`openid esapi-scope`
`client_id`	Your Application ID
`client_secret`	Your Application Secret
`username`	Your API Key
`password`	Your API Secret

URL Encoded

When the body is sent it should be url encoded as below.

grant_type=password&scope=openid%20esapi-scope&client_id={Application ID}&client_secret={Application Secret}&username={API Key}&password={API Secret}

Response

{
    "access_token": "{Your Access Token}",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Troubleshooting

If you get an error response of invalid_scope your application may be configured for a specialised scope instead of esapi-scope. Check your Application at Locatrix Account Management in the Application section, and ensure that the same Allowed Scopes are being passed through in the bearer token request (space separated).