Authentication API

Every call to the platform carries two credentials: an API key that identifies your tenant, and a short-lived OAuth2 access token that identifies the caller.

Overview

The API key is issued once, during onboarding, and never changes. The access token you request yourself and refresh as it expires. Both travel on every request:

Authorization: Bearer <access_token>

?api-key=<apiKey>

The API key is required on the token call as well - 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 Sovereign Solutions during onboarding, subject to our Terms of Service.
Authorization: Bearer - 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

Endpoints

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

Issue an access token

POST /oauth/token

Request Parameters

Parameter	In	Type	Required
`grant_type`	body	string	No
`username`	body	string	No
`password`	body	string	No

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

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

Response Schema

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

Refresh an access token

POST /oauth/token

Request Parameters

Parameter	In	Type	Required	Description	Example
`grant_type`	body	string	No	Always `refresh_token` for this call.
`refresh_token`	body	string	No	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 Schema

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.

Example

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'

Overview​

What each credential is for​

API reference​

Endpoints​

Issue an access token​

Refresh an access token​

Example​