In order to leverage Compliance's API, customers must first authenticate with Compliance via the Oauth 2.0 client credentials grant. This article will explain how to generate the required credentials (Client ID and Client Secret) in Compliance.
Role Requirements
Administrator
Custom Role with Manage Rights to API Access permissions as follows:
How to generate a Client ID and Client Secret
Navigate to the integrations administration menu: Administration > Integrations.
Click New Client Credentials.
Select the user who will be programmatically authenticating with Compliance. If the user is a custom role, we recommend granting this user Manage Import permissions.
Copy and paste the Client ID and Client Secret into a secure location. Please note that once the dialog is closed, you will no longer be able to retrieve your Client Secret. If you lose the Client Secret, you will need to generate a new credentials.
Security Considerations
Client Credentials are automatically tied to the permissions of the user they are associated with. If using a custom role, we strongly recommend creating a role with only the permissions required for the API integration tasks.
A custom role with "Imports" and "API Access" management permissions should satisfy the most common use case of scheduling data import tasks.
Using Client Credentials
Compliance's authenticated endpoints can be tested directly through our API Documentation. Once you have retrieved your client credentials you can generate an access and refresh token from the client credentials "Auth" endpoint:
In the API documentation, click Auth > Auth:token in the left side panel.
In the sample body in the right-hand side, replace the example Client ID and secret with the credentials generated from your account.
Click Send API Request
If successful, the response below will contain your access and refresh token, which expire after a certain amount of time. The access token can be used to test API requests throughout the documentation pages.
Importing Users
The most common use-case with our API is to import users into the web portal. This uses the https://api.threatswitch.com/v1/imports endpoint.
Check out THIS page in the documentation for more details on that process. To swap between different Body examples (JSON or CSV) when testing, click the Examples button above the Body section and choose from the dropdown list.
