Token instrospection for channel identification

When OAuth integrations install Front channels, the name of the created channel will default to the channel type name and a random string will be assigned as the address of the channel. This can make it challenging for teammates to identify the corresponding channel or number in Front.

To address this, Front supports the ability for external services to provide a custom channel name and address during the OAuth flow by using the OAuth2 Token Introspection Standard.

What is token instrospection?

Token introspection is an additional step in the OAuth2 flow where the client sends a request to the external server to retrieve information about the provided access token. This request allows Front to obtain details such as the name and address of the channel from the external service.

The implementation is based on the OAuth 2.0 Token Instrospection specification.

Implementing token instrospection

To enable this functionality, the Token Introspection URL must be configured in the Servers tab of your app.

After configuring the URL, incorporate the following process in your channel flow:

1. Token Introspection Request
   After acquiring the access token during the OAuth flow, the client makes a POST request to the configured token introspection URL.
   The request should include the following components:
   • Authentication—Using Basic Auth, providing the client_id and client_secret as credentials.
   • Request Body—Include the access_token to be examined in a field named token.
2. Token Introspection Response
   The response must:
   • Contain a Boolean field named active, which indicates whether the token is valid.
   • Provide the following custom fields required by Front:
     • front_channel_name—The custom name for the channel.
     • front_channel_address—The address of the channel.

       📘

       The front_channel address must be unique for each channel of a given application channel.

       The external service is responsible for ensuring the uniqueness of the address. If duplicate addresses are provided, the channel installation will fail.

Request example

POST https://your-introspection-url.com/introspect

Headers

Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/json

Body

{
  "token": "<access_token>"
}

Response example

For a valid token:

Status: HTTP 200 Ok

Body

{
  "active": true,
  "front_channel_name": "Support WhatsApp Line",
  "front_channel_address": "+1234567890"
}

For an invalid token:

Status: HTTP 401 Unauthorized

Body

{
  "active": false
}