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.
Note: The latest version of our external API is now available as a full release. Consequently, the v1.0, v1.1, v1.2 API's will be deprecated by July 2023.
For more details on the new version, please visit the External Company API v2.0 Knowledge Base article.
Should you be interested in enabling the v2.0 API, please contact your Customer Success Manager for further details.
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 |
grant_type | Should always be grant type "client_credentials" when using External API v1 |
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 response
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:
Github link to API applications
In this link to Github, you can find a couple of applications which might be useful.
You can find a Slack announcer, a similar application that could be used for Teams, as well as a go library and a cidc-plugin