This article aims to provide you with all information needed to realize an API integration between your company’s back-end systems and the Intigriti API. It will give you an overview of the current scope of the interface, the ways to address it and how to retrieve the information from it that you desire.


Getting started

Since securing the contents on the intigriti platform is one of our top priorities, some prerequisites must be met prior to being able to use the API. When kicking off implementation of an integration, please make sure to get Client Credentials
(OAuth 2.0) via Admin > Integrations > Intigriti External API.


Make sure to store your Client Credentials in a secure way. They will only be visible while requesting them. In case you lose your Client Credentials, you will need to delete your credentials and request a new Client ID and Secret.

Authentication

In order to consume our API services, the mandatory first step will always be authentication to the platform. In this step you will let the platform verify your identity and (in case of success) provide you with an Access Token. A valid access token will be necessary when addressing any API endpoint on the platform.

Intigriti uses Open ID Connect to provide access tokens. This standard provides temporary tokens that give access to a resource for a limited duration of 14 days.

Note: The access token needs to be reused until it expires or is invalidated by Intigriti. Be sure to request a new access token when the API returns a 401.

Client - credentials flow

Our API is currently setup as a M2M service and uses the client credentials flow. More information on the client credential flow can be found here and here.

Note: Make sure to never call our API directly from an untrusted medium ex. a browser. This could potentially lead to the leakage of your Client Secret!

Since this is a standardized flow, there is a high chance there are libraries available in your programming language. This will take the heavy lifting of retrieving an access token away.

Authentication endpoint specifications

Following specifications can be used to retrieve an access token:

POST https://login.intigriti.com/connect/token


Input parameters

When addressing the endpoint, you should provide following input parameters in the form-data of your request:

client_id

The client ID that you obtained from intigriti

client_secret

The client secret that you obtained from intigriti

client_id: <client_id>
client_secret: <client_secret>
grant_type: client_credentials

Request Content-Type

You must provide a valid Content-Type header to authenticate.

Content-Type: application/x-www-form-urlencoded 

Valid response

When the request to this endpoint was successfully processed by the endpoint, you will receive following parameters:

access_token

The token that needs to be used for later requests

expires_in

The number of seconds this token is valid

token_type

The type of token, this will always be a ‘Bearer’ token

scope

The scope of applications to which this token is applicable

The response will have following structure:

Http 200 OK
{
"access_token": "<access_token>",
"expires_at": 1209600,
"token_type": "Bearer",
"scope": "external_api"
}

Invalid respons

When the request was not executed successfully, any one of following HTTP headers will be received:

Http 400 Bad Request
Http 401 Unauthorized


Technical Specifications

The API is stateless and REST-full. It uses following HTTP requests to interact with the platform data:

  • GET - retrieve one or more objects from the platform

  • PUT - update or change the state of an object on the platform

  • POST - create an object on the platform

  • DELETE - remove an object from the platform

Interaction with the API always uses the JSON-format, for input as well as output. Important too is that any file-link generated by the API, will have a maximal validity of 1 hour.

Any requests regarding API scope are more than welcome and can be channeled through your success manager.

Versioning

Intigriti APIs are versioned to ensure applications and services continue to work as APIs evolve.

URL structure: https://api.intigriti.com/external/{version}/{resource}

Intigriti APIs use a Major.Minor versioning scheme. For every breaking API change, the major version is bumped. Clear examples of breaking changes are:

  • Removing or renaming APIs or API parameters

  • Changes in behaviour for an existing API

  • Changes in Error Codes and Fault Contracts


Be aware that in case the version is not specified in the source URL, the default API version 1.0 is addressed. This version will soon be deprecated, we advise to use the latest available version when implementing our API (currently 1.2)

Endpoints

An overview of the available endpoints including their specifications, input parameters and responses can be found on our Swagger.

Don't forget to add your access token as a header to every request.

Authorization: Bearer <access_token>

To make sure Swagger does this as well, authorize and provide the necessary info:


Did this answer your question?