Token instrospection for channel identification

When OAuth integrations install Front channels, the name of the created channel will default to the application channel 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—(Required if your app channel uses private credentials , omit otherwise)The user-facing name for the channel.
     • front_channel_address—(Required if your app channel uses private credentials , omit otherwise) The unique address or identifier 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.

     • resource_owner_id—(Required if your app channel uses shared credentials , omit otherwise) This field identifies the scope of the credentials granted to the user. Use a company ID for company-level resource access, or a user ID for user-scoped access.
     • resource_owner_name—(Required if your app channel uses shared credentials , omit otherwise) Provide a descriptive name for the resource_owner_id, such as a company name or a user's email address.

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 private credentials

For a valid token:

Status: HTTP 200 Ok

Body

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

Response example for shared credentials

For a valid token:

Status: HTTP 200 Ok

Body

{
  "active": true,
  "resource_owner_id": "usr_23kdkd948fk",
  "resrouce_owner_name": "[email protected]"
}

Response example for an invalid token:

Status: HTTP 401 Unauthorized

Body

{
  "active": false
}