Intercom Install & Auth Skill

Intercom Install & Auth

Overview

Set up the official intercom-client TypeScript SDK and configure authentication via access tokens (private apps) or OAuth (public apps).

Prerequisites

Node.js 18+
npm, pnpm, or yarn
Intercom workspace with Developer Hub access
Access token from Configure > Authentication in your app settings

Instructions

Step 1: Install the SDK

npm install intercom-client

The package exports IntercomClient and all TypeScript types under the Intercom namespace.

Step 2: Configure Access Token Authentication

Access tokens authenticate private apps that access your own Intercom workspace.

import { IntercomClient } from "intercom-client";

const client = new IntercomClient({
  token: process.env.INTERCOM_ACCESS_TOKEN!,
});

Store the token securely:

# .env (add to .gitignore)
INTERCOM_ACCESS_TOKEN=dG9rOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6

# Verify .gitignore includes .env
echo '.env' >> .gitignore

Step 3: Verify Connection

async function verifyConnection() {
  try {
    // List admins to verify the token works
    const admins = await client.admins.list();
    console.log("Connected! Admins:", admins.admins.length);
    for (const admin of admins.admins) {
      console.log(`  - ${admin.name} (${admin.email})`);
    }
  } catch (error) {
    if (error instanceof Error) {
      console.error("Connection failed:", error.message);
    }
  }
}

verifyConnection();

Step 4: OAuth Setup (Public Apps)

For apps that access other workspaces, configure OAuth:

// Step 1: Redirect user to Intercom authorization
const authUrl = `https://app.intercom.com/oauth?client_id=${CLIENT_ID}&state=${STATE}`;

// Step 2: Exchange code for token at your callback endpoint
async function handleOAuthCallback(code: string): Promise<string> {
  const response = await fetch("https://api.intercom.io/auth/eagle/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: process.env.INTERCOM_CLIENT_ID,
      client_secret: process.env.INTERCOM_CLIENT_SECRET,
      code,
    }),
  });

  const data = await response.json();
  return data.token; // Use this token for API calls
}

// Step 3: Initialize client with OAuth token
const client = new IntercomClient({ token: oauthToken });

API Versioning

Specify the API version header to pin behavior:

const client = new IntercomClient({
  token: process.env.INTERCOM_ACCESS_TOKEN!,
});

// All requests use Bearer token in Authorization header:
// Authorization: Bearer <token>
// Intercom-Version: 2.11

The current stable API version is 2.11. The SDK handles this automatically.

OAuth Scopes Reference

| Scope | Access Granted | |-------|---------------| | Read admins | List workspace admins | | Read/write contacts | Create, update, search contacts | | Read/write conversations | Manage conversations and replies | | Read/write messages | Send outbound messages | | Read/write articles | Manage Help Center content | | Read/write tags | Tag contacts, companies, conversations | | Read/write events | Submit and read data events | | Read/write companies | Manage company records |

Error Handling

| Error | HTTP Code | Cause | Solution | |-------|-----------|-------|----------| | unauthorized | 401 | Invalid or expired token | Regenerate in Developer Hub | | forbidden | 403 | Missing OAuth scope | Add required scope in app config | | token_revoked | 401 | Token was revoked | Generate new access token | | invalid_grant | 400 | OAuth code expired | Restart OAuth flow |

import { IntercomError } from "intercom-client";

try {
  await client.contacts.list();
} catch (error) {
  if (error instanceof IntercomError) {
    console.error(`Intercom error: ${error.statusCode} - ${error.message}`);
    if (error.statusCode === 401) {
      console.error("Token invalid. Regenerate at app.intercom.com > Developer Hub");
    }
  }
}

Resources

Next Steps

After successful auth, proceed to intercom-hello-world for your first API call.

Agent Skills: Intercom Install & Auth

Install this agent skill to your local

Skill Files