Introduction

The instellix REST API uses 2-legged OAuth, which is part of the OAuth 2.0 specification - the industry-standard protocol for authorization.

To access the API endpoints the following flow needs to be implemented:

1. authenticate via HTTP Basic Authentication, providing your credentials, to obtain an access token
2. subsequently use the access token to authorize every request to the API itself

Environments and API Access

The sandbox environment is the default test environment for our customers and mirrors the production system in terms of functionality, ensuring that all features are available and can be tested under comparable conditions, excluding production-scale performance characteristics.

The stage environment is available to selected customers and provides early access to upcoming features for preview and validation.

API authentication and authorization flow

Authentication to obtain an access token

The URL to acquire the access token is

https://api.instellix.io/{realm}/oauth2/token.

In the request to this URL you need to provide the HTTP header 'Authorization' which contains the authorization method and a space (= "Basic ") appended by a Base64-encoded string of the scheme client_id:client_secret. Check the following sample for a better understanding:

Concatenated client id and secret | my_client_id:my_client_secret
Base64 encoded string             | bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=
HTTP Header in POST request       | Authorization: Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=

Following a simple cURL example how this request could look like and the response to it:

curl --location --request POST 'https://api.instellix.io/{realm}/oauth2/token' \
--header 'Authorization: Basic {your base64 encoded client_id:client_secret}'
--form grant_type=client_credentials

{
    "access_token": "{your access token is returned here}",
    "token_type": "bearer",
    "expires_in": 269
}

👍

Access token should be cached and reused until expiry to improve performance!

The access token is valid for a certain amount of time (depending on the security config on your instance, default is 5 minutes) and should be reused for consecutive requests until expiry.

Requesting a new access token for each and every API request will considerably slow down performance and is bad practice in general. Constant polling of new tokens within a 5s window can additionally result in a 401 status response for otherwise correct credentials.

Authorize every API call providing the access token

For every request to the API the access token must be provided to authorize the call for the requested resource, again using the HTTP header 'Authorization':

curl --location --request GET 'https://api.instellix.io/some-resource \
--header 'Authorization: Bearer <your access token>'

Access control using scopes

In OAuth2, scopes define which resources or specific actions a client is allowed to access within an API.

The scopes required for authorizing a call to our API are part of a role-based access control (RBAC) approach, as described in instellix Rights and Roles documentation. Each account — whether a personal user account or one created for API access — is associated with one or more of these specific roles. Each role includes a set of access rights representing the scopes for which the token is issued.

The scope required for each API operation can be found in this API reference. Note that the scopes themselves are not embedded in the issued access token, as we issue opaque tokens that intentionally exclude scopes for security reasons.

Token validity

Our tokens contain expires_in which indicates the validity of the token in seconds in accordance with RFC 6749.