Skip to content

Fin Agent API - Setup

'Fin Agent API' is currently under managed availability

Please reach out to your accounts team to discuss access and tailored, hands-on support.

Installation

API key

  1. In your Intercom workspace, go to Fin AI Agent from the sidebar.
  2. Then click on the “Deploy” nav item to expand its options.
  3. You should see an “API” item. Click this, and you should see the following page: API Key
  4. From there, click “Install” to get your API key.
  5. You’ll see two buttons beside the API key, for copying to clipboard and revealing the key in that respective order.
  6. Copy the key
  7. Use this API key in your requests as a Bearer token.

OAuth Scopes & Permissions

The Fin Agent API access token is created with minimal OAuth scopes following the principle of least privilege for enhanced security.

Default Scope

Your Fin Agent API token has the following OAuth scope:

  • write_conversations - Allows replying to, marking as read, and closing conversations

This scope is sufficient for all Fin Agent API operations (/fin/start and /fin/reply endpoints).

Fin Agent API Token Scopes

Token Security

Server-to-Server API Only

The Fin Agent API is designed exclusively for server-to-server communication. Your API key must:

  • Only be used in backend/server-side code
  • Never be exposed in client-side code (JavaScript, mobile apps, browser extensions)
  • Never be committed to public repositories or shared publicly

Even with reduced scopes, an exposed token could be used to send messages on behalf of your organization or access conversation data.

Reduced Permission Surface

Fin Agent API tokens have significantly reduced permissions compared to general-purpose API keys. This means:

  • If compromised, the token can only be used to interact with conversations
  • The token cannot access user data, export reports, manage admins, or perform other administrative actions
  • This 97% reduction in permission surface area minimizes security risk

Using the Token for Other APIs

Token Scope Limitations

The Fin Agent API token is specifically designed for the Fin Agent API endpoints. If you need to call other Intercom APIs (such as the REST API for users, companies, or other resources), you should:

  1. Create a separate API key or App with the appropriate scopes for those endpoints
  2. Use different tokens for different API integrations to maintain security boundaries

Do not attempt to use the Fin Agent API token for other Intercom API endpoints, as it lacks the necessary permissions.

Customizing Scopes

If you need to adjust the OAuth scopes for your Fin Agent API token:

  1. Navigate to Settings → Developer Hub → App Packages
  2. Find your Fin Agent API app package
  3. Click on the OAuth section to view and modify scopes
  4. Regenerate your token for changes to take effect

Note: While you can add additional scopes, we recommend keeping only the scopes you actually need for security best practices.

Notification Method

Configure a Webhook to receive notifications from Fin. Notification Method

  1. You'll need to provide a URL to receive notifications.
  2. Initially, the Webhook secret will be empty. Once you click save, a secret will be generated and displayed. Webhook Secret
  3. Now, you can use the buttons to copy the secret to clipboard, or reveal the secret.
  4. Use this secret to validate the webhook requests.

How to use your API key

Please refer to Intercom’s authentication guidelines for more information.

Webhook Validation

All webhook requests will include an X-Fin-Agent-API-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Validation can be done by generating a signature using the request body and the signing secret from the settings, and comparing it with the aforementioned header value.

We compute the value of this X-Fin-Agent-API-Webhook-Signature header by creating a signature using the body of the JSON request and your Webhook secret value, which you can find in the Webhook settings of your API.

The signature is the hexadecimal (64-byte) representation of a SHA-256 signature computed using the HMAC algorithm as defined in RFC6234.

POST https://example.org/hooks
X-Fin-Agent-API-Webhook-Signature: sha256=21ff2e149e0fdcac6f947740f6177f6434bda921
Content-Type: application/json

Testing

We have provided a sample Postman collection that can be used for testing this locally. Simply open Postman from the link above and update the following environment variables:

  • bearerToken: your API key
  • externalConversationId: An identifier for your conversation