Authentication API

Issues the short-lived OAuth2 access token that tenant APIs need alongside your API key.

---

Overview

The API key is issued once, during onboarding, and never changes. The access token you request yourself and refresh as it expires. Which of them a call needs depends on the API:

API	Credentials
API key only (location, map and route APIs)	?api-key=<apiKey>
Requires Intelomatic tenant	Authorization: Bearer <access_token> and ?api-key=<apiKey>
The token call on this page	?api-key=<apiKey> - it is what tells the identity server which tenant is asking

What each credential is for

• api-key query parameter - identifies the tenant. Scopes every request to your workspace and your data. Issued by Intelomatic during onboarding, subject to our Terms of Service.
• Authorization: Bearer - tenant APIs only. Identifies the user or service account making the call, and expires (expires_in, in seconds). Request a new one with the refresh token rather than re-sending credentials.

Which APIs need a tenant?

Some APIs work with the API key alone; others need a provisioned Intelomatic tenant. Each API page carries a badge saying which, and the API catalogue lists it per API.

---

API reference

Authentication · API key only

Quick try

curl

curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/authen/oauth/token?api-key=$API_KEY' \
  -d 'grant_type=password' \
  -d 'username=$USERNAME' \
  -d 'password=$PASSWORD'

Endpoints

Method	Path	Purpose
POST	/oauth/token	Issue an access token
POST	/oauth/token	Refresh an access token

Issue an access token

POST https://api-gw.sovereignsolutions.com/gateway/{tenant}/oauth/token

Auth: api-key query parameter only - this call issues the bearer token

Request parameters

Parameter	In	Type	Required	Description
grant_type	body	string	-
username	body	string	-
password	body	string	-

Request body (application/x-www-form-urlencoded)

grant_type=password
username=<your_username>
password=<your_password>

Response

200 OK

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<token>"
}

Field	Type	Description
access_token	string
token_type	string
expires_in	integer
refresh_token	string

Errors: non-2xx responses use the standard status codes listed on Errors.

Refresh an access token

POST https://api-gw.sovereignsolutions.com/gateway/{tenant}/oauth/token

Auth: api-key query parameter only - this call issues the bearer token

Request parameters

Parameter	In	Type	Required	Description
grant_type	body	string	-	Always refresh_token for this call.
refresh_token	body	string	-	The refresh_token returned by the previous token call.

Request body (application/x-www-form-urlencoded)

grant_type=refresh_token
refresh_token=<refresh_token>

Response

200 OK

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "expires_in": 86399,
  "refresh_token": "<token>"
}

Field	Type	Description
access_token	string
token_type	string
expires_in	integer
refresh_token	string

Same endpoint as the password grant; grant_type=refresh_token swaps a refresh token for a new access token without re-sending the username and password.

Errors: non-2xx responses use the standard status codes listed on Errors.