Authentication overview

Before you start

• You need a Power User profile to generate credentials in Control Panel.
• Each Interact API authenticates differently. Confirm which API you are using before you generate a credential.

Overview

Interact has several APIs, and each one uses its own type of credential. The same idea — a string you keep secret and send with every request — appears under different names depending on the API. This page gives each credential a single canonical name and shows how to generate and send it, so you do not have to guess which "key" a given guide is referring to.

There are three distinct credential types:

• Authentication token — a bearer token used by SCIM v2.0 and General Profile Sources.
• Secret key — a per-connector key used by the Workplace Search API.
• API key and secret — a key/secret pair used by the REST API to log in as a specific user.

Important: Treat every credential as a secret. Never include one in front-end code or return it to the browser, and rotate credentials regularly.

Comparison table

Note: The header name X-ApiKey is reused by two different APIs. A General Profile Sources credential is an authentication token; a Workplace Search credential is a secret key. They are not interchangeable.

Authentication token (SCIM v2.0)

SCIM v2.0 uses an OAuth bearer token, called the authentication token, that you include in the Authorization header.

To generate it, sign in as a Power User and go to Control Panel > Profile Sources. Select SCIM, enter a user-friendly name, select Generate Key, and make sure Active is checked. Keep a copy of the authentication token, because you need it to configure SCIM provisioning in your system of record. You can retrieve it later by editing the profile source.

Send the token with every request:

Authorization: Bearer {{auth_token}}

Full endpoint details live in the API Reference. See SCIM v2.0.

Authentication token (General Profile Sources)

General Profile Sources also uses an authentication token, but you send it in the X-ApiKey header rather than as a bearer token.

To generate it, sign in as a Power User and go to Control Panel > Profile Sources > Other Source. Enter a unique Name and an Authorisation Token. The token verifies incoming data files against the source when the API is called.

Send the token in the X-ApiKey header when you post your XML file:

$endpoint = "https://{{intranet_url}}/api/umi/{{source_id}}/upload"
$xmlPath = "C:\{{path_to_XML}}"
$authToken = "{{auth_token}}"

Invoke-RestMethod -Uri $endpoint -Method Post -InFile $xmlPath -ContentType "multipart/form-data" -Headers @{ 'X-ApiKey' = $authToken }

curl --request POST "https://{{intranet_url}}/api/umi/{{source_id}}/upload" \
  --header "X-ApiKey: {{auth_token}}" \
  --header "Content-Type: application/xml" \
  --data-binary "@{{path_to_XML}}"

Tip: SCIM v2.0 is the preferred method for profile synchronisation. Use it instead of General Profile Sources for new integrations.

See General Profile Sources.

Secret key (Workplace Search)

The Workplace Search API authenticates per connector with a secret key. This API is distinct from the REST API: you do not need to authenticate with the REST API to use Workplace Search.

To generate the key, sign in as a Power User and go to Control Panel > Developer Framework > Workplace Search. Select Create New Connector, choose Custom, and select Next. Enter a Name, then generate and add a Secret Key.

Warning: Never expose your secret key in public websites or client-side code. Use it only inside your external application. The secret key cannot contain angle brackets.

Send the key in the X-ApiKey header with every request to the Workplace Search API:

X-ApiKey: {{secret_key}}

See Workplace Search Custom Connectors and How to set up a Workplace Search Custom Connector.

API key and secret (REST API)

The REST API authenticates with an API key and secret pair, which lets you act as a specific user.

Create an API key in the security settings of Control Panel. A secret is generated automatically at the same time. The secret is shown only once and cannot be retrieved again, so store it securely.

Warning: Anyone with the API key and secret can access the intranet APIs as any user. Never include them in front-end code, and delete a key immediately if you suspect it has been compromised.

Unlike the other credentials, the API key and secret are not sent on every request. You exchange them for an access token using the authorization_code grant type, then send that access token in the Authorization header:

var body = new Dictionary<string, string>();
body.Add("grant_type", "authorization_code");
body.Add("code", $"{key}__{secret}");
body.Add("context", "KeySecret");

// Post to /token?personid={personId} with the X-Tenant header
// The response contains access_token and refresh_token

See the API reference for the endpoints that use this flow.

Related

• REST API
• Get started with Interact
• Glossary