To set up new authentication methods for Custom Actions, 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 Action 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 Action, the action will use the most recently fetched token in the Action request. If the request fails with a “401 Unauthorized” response, the token will be refreshed by sending an HTTP Request to your Authentication Endpoint URL. The Action request will then be retried with 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 Action "Logs" tab.
User tokens
User tokens allow authenticating actions 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 Actions. 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 Action
Once your token type is created:
Choose an Action you’d like to configure the authentication token for.
Select your new token in "HTTP Headers" section.
This setup allows you to trigger Actions using that token - either through Workflows or Fin. The Action 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
});
That’s it! If you’d like to learn more about user token type or see additional examples, feel free to reach out. We're happy to help.
Logic
Text based tokens are straightforward, the Action will use the assigned token value whenever it tests or sends a live action request. HTTP Request tokens have a more involved flow. For both testing and live actions, the Action will first use the most recently retrieved token. If the request fails, it will then send a refresh request and try the action again. This will only occur once to avoid an infinite loop.
If the action keeps failing due to refresh requests failing, it will trigger the circuit breaker in the same way that all Actions can for repeated failures of a single action.
Known limitations
Currently neither the Text or HTTP Request authentication token types support different authentication request details per end user. 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