To set up new authentication methods for Data connectors, go to Settings > Integrations > Authentication and click New token.
There are three authentication token types to choose from:
Text tokens
Text tokens are static tokens. You can set the token's name, description, value, token prefix, and the key for the request header containing the token, which will be inserted into the Data connector request.
HTTP Request tokens
HTTP Request tokens are dynamic. You configure an HTTP request to your Authentication Endpoint that will refresh the token when needed. These tokens must be tested from the Authentication Token UI before saving them. You can set the token's name, description, and then the fields that affect the request itself. These are the HTTP request method, URL, HTTP headers, and any key-value pairs.
You should test the token by clicking Test request and then specify the token's location in the response, the token prefix and the key for the request header.
If an HTTP Request token is assigned to a Data Connector, the connector will use the most recently fetched token for its requests. If a request returns a “401 Unauthorized” response, the token will be refreshed by sending an HTTP Request to the specified Authentication Endpoint URL. The original Data Connector request will then be retried using the newly fetched token.
If your server is returning a 200 for an access denied response, we won't refresh the token. You'll need to update your servers to return a 401 in this case.
If there is a problem refreshing a token, the issue will be logged in the Data connector "Logs" tab.
User tokens
User tokens allow authenticating Data connectors using a user-defined token. These tokens are created and updated by 3rd party systems. One of the most popular example of such token is JSON Web Tokens (JWT).
JWT is a secure way to verify user identity. You can now use this new type of authentication token to secure your Data connectors. This allows for more flexible and secure communication between your systems and Intercom. Here's how to set it up:
Set up a new token type
Give your token a name.
Choose User as the Type.
Set the Token prefix and Header as needed.
Use the token in an Data connector
Once your token type is created:
Choose an Data connector you’d like to configure the authentication token for.
Select your new token in "HTTP Headers" section.
This setup allows you to trigger Data connectors using that token - either through Workflows or Fin. The Data connector will continue to work even if the token value is updated, as it will be refreshed in real time to ensure uninterrupted authentication.
Creating and updating user tokens
All user token management is handled by 3rd party systems.
Intercom('boot', {
app_id: 'abc12345',
email: 'john.doe@example.com',
created_at: 1234567890,
name: 'John Doe',
user_id: '9876',
auth_tokens: {
security_token: 'abc...' // JWT
}
});
These 3rd party systems are also responsible for updating the security token and periodically refreshing it.
Intercom('update', {
app_id: 'abc12345',
auth_tokens: {
security_token: 'bcd...' // JWT
}
});
Intercom('setAuthTokens', {
security_token: 'abc...' // JWT
});
# Swift
Intercom.setAuthTokens({
security_token: 'abc...' // JWT
});
# Kotlin
Intercom.client().setAuthTokens({
security_token: 'abc...' // JWT
});
Email verification with a One-Time Passcode (OTP)
Email verification for Data connectors with OTP provides an additional verification step before an Data connector is used by requiring customers to verify their identity through a unique, time-sensitive code sent via email.
This method adds an extra layer of security on top of user authentication tokens (e.g., JWTs). When enabled, customers must complete the email-based verification process before a Data connector can proceed. This helps ensure that only authorized users can perform sensitive operations and prevents misuse of automated workflows.
Logic
Text-based tokens are straightforward — the Data connector uses the assigned token value whenever it tests or sends a live Data connector request.
HTTP Request tokens follow a more involved flow. For both testing and live Data connectors, the Data connector will first use the most recently retrieved token. If the request fails, it will send a refresh request and then retry the Data connector using the new token. This retry occurs only once to avoid an infinite loop.
If the data connector continues to fail due to refresh requests failing, it will trigger the circuit breaker, just like any Data connector that encounters repeated failures.
Known limitations
Currently neither the Text or HTTP Request authentication token types support different authentication request details per customer. Usually this is requested as a full OAuth flow.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts