Skip to content

Authentication

Introduction

Access to Spectus's API layer is protected through our Internal Identity Provider (IDP) which adheres to the OpenID Connect and OAuth2 standards.

In order to interact with the API, you must authenticate against our identity provider using the OAuth2 client credentials grant flow, which is the flow used for server-to-server authentication, then you will receive the tokens needed to interact with our APIs. In the following sections, you’ll get an overview of how to perform authentication and how to interact with our external APIs layer.

Authentication

  1. Once you activate the external APIs feature, a dedicated OAuth2 client will be created for your organization: you’ll get a Client Id and a Client Secret (provided by Spectus) and you’ll use them to authenticate against our Identity Provider, using Oauth2 client credentials grant flow.

The identity provider can be reached at the URL https://auth.spectus.ai and, more specifically, you’ll have to interact with the token endpoint, which can be found at the following address:

https://auth.spectus.ai/auth/realms/Customers/protocol/openid-connect/token

  1. As a result of a correct login process, a set of tokens will be minted by the Identity Provider: those tokens will be used by the user to interact with our APIs.

Please note that tokens have an expiration time, so they’ll need to be refreshed properly (interacting with our IDP). For more information please have a look at the next sub-section JSON Web Tokens (JWT) and Refresh Token Process

  1. The login/authentication process consists in a simple HTTP POST request to the token endpoint, providing the grant_type (set to “client_credentials”), clientId and clientSecret form parameters in the body of the request (Content-Type: application/x-www-form-urlencoded).

Here’s an example of a login request and response through our identity provider:

Request

POST to https://auth.cuebiq.com/auth/realms/Customers/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Body:
grant_type: client_credentials
client_id: <clientId>
client_secret: <clientSecret>

Response

{
 "access_token": <encoded_access_token>,
 "expires_in": 3600,
 "refresh_expires_in": 21600,
 "refresh_token": <encoded_refresh_token>,
 "token_type": "bearer",
 "not-before-policy": 1571918224,
 "session_state": "aa3a7f72-f1de-4446-a09e-20d93c9a0ace",
 "scope": "profile email"
}

JSON Web Tokens (JWT)

The result of a correct login process will return a set of tokens to the caller, that can be used to interact with our APIs.

More specifically, two kinds of tokens will be released:

  • access_token: to be used to interact with our external APIs. You’ll have to put this token inside the Authorization header with the HTTP Bearer authentication scheme. This token generally expires before the refresh token and it needs to be refreshed properly against our Identity Provider.
  • refresh_token: to be used to refresh an expired access token. Once your access token has expired you can use this token with a simple POST to obtain a new set of with new expiration times. See the Refresh Token process section to understand how to perform this process.

Refresh Token Process

Every token minted by our Identity Provider (both access and refresh tokens) has an expiration time: customers will not be able to access the APIs layer with an expired access token. In order to avoid using expired access tokens, a periodic refresh process must be put in place by the customer system. This is where the refresh token (that you’ve received during the login process) enters the scene: this particular token must be used by the customer, to retrieve another set of fresh tokens (access and refresh) against Keycloak.

As the login process, the refresh procedure consists of a simple request to the Keycloak’s token endpoint, more specifically a POST providing the grant_type (set to “refresh_token”), refresh_token, clientId, and clientSecret form parameters in the body of the request (Content-Type: application/x-www-form-urlencoded). Here’s an example of a refresh token request and response through our identity provider:

Request

POST TO https://auth.spectus.ai/auth/realms/Customers/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Body: 
client_id: <clientId>
client_secret: <clientSecret>
grant_type: refresh_token
refresh_token: <encoded_refresh_token>

Response

{
 "access_token": <encoded_access_token>,
 "expires_in": 3600,
 "refresh_expires_in": 21600,
 "refresh_token": <encoded_refresh_token>,
 "token_type": "bearer",
 "not-before-policy": 1571918224,
 "session_state": "aa3a7f72-f1de-4446-a09e-20d93c9a0ace",
 "scope": "profile email"
}

As you can see, if everything goes right, you’ll receive a brand new access token and a brand new refresh token. You’ll have to use the former to interact with external apis, and the latter to perform the next refresh process that will be needed when the new access token will expire.

Interacting with our API Layer

Our APIs are available through the following public URL:

https://api.spectus.ai/

Every call must be authenticated, so please don’t forget to provide the access token inside the Authorization Header with the HTTP Bearer Authentication scheme.

You’ll be able to operate only on your organization’s resources (tenancy). This means that your organization id must be explicitly set inside the url when required, otherwise the user will receive a 403 Forbidden HTTP error code.

Please have a look at the How to know my customerId section to understand how to find your organization id.

Here’s an example of a simple API request through our public APIs endpoint:

POST to https://api.spectus.ai/v1/customers/{customerId}/jobs
Authorization: Bearer <encoded_access_token>
Body:
<body_of_the_request>

How to know my customerId

A Spectus representative will provide your customerId, clientId, and clientSecret. If this doesn’t happen, please find the customerId inside the clientId: it’s the number after the last “-” character (i.e. for the clientId test-test-123, the customerId is “123”). 

Obtaining Swagger/OpenAPI definition

You can obtain the OpenAPI definition of our API by hitting the following endpoint:

  • https://api.spectus.ai/openapi - Based on the Accept header included in the request, returns the generated documentation in YAML (default) or JSON format.