---
name: intercom-install-auth
description: |-
  Install and configure Intercom API authentication with access tokens or OAuth.
  Use when setting up a new Intercom integration, configuring API credentials,
  or initializing the intercom-client SDK in your project.
  Trigger with phrases like "install intercom", "setup intercom",
  "intercom auth", "configure intercom API key", "intercom access token".
allowed-tools: Write, Bash(npm:*)
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
  - saas
  - support
  - messaging
  - intercom
compatibility: Designed for Claude Code
title: intercom-install-auth
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/error-handling.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/error-handling.md), [references/examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/examples.md), [references/oauth.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/oauth.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/intercom-install-auth`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/intercom-install-auth`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/intercom-install-auth`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/intercom-install-auth --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/intercom-install-auth --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Intercom Install & Auth

## Overview

Set up the official `intercom-client` TypeScript SDK and configure authentication via access tokens (private apps) or OAuth (public apps). This skill installs the SDK with a Bash npm command, uses Write to create the client config and `.env`, and verifies the connection.

## 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

```bash
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. Use Write to create the client module and a `.env` holding the token (add `.env` to `.gitignore`):

```typescript
import { IntercomClient } from "intercom-client";

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

See [examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/examples.md) for the full `.env` setup and secure-storage steps.

### Step 3: Verify Connection

List admins to confirm the token authenticates end-to-end:

```typescript
const admins = await client.admins.list();
console.log("Connected! Admins:", admins.admins.length);
```

The complete verification function (with error handling and expected output) is in [examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/examples.md).

### Step 4: OAuth Setup (Public Apps)

For a **public app** that accesses other workspaces, run the OAuth authorization → token-exchange flow, then initialize the client with the returned token:

```typescript
const client = new IntercomClient({ token: oauthToken });
```

Full OAuth exchange, API-version pinning, and the scope matrix are in [oauth.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/oauth.md).

## Output

Running this skill produces:

- `intercom-client` installed in `node_modules` and added to `package.json`.
- A configured `IntercomClient` module authenticated via access token or OAuth.
- A `.env` holding `INTERCOM_ACCESS_TOKEN` (private app) or `INTERCOM_CLIENT_ID` / `INTERCOM_CLIENT_SECRET` (OAuth), with `.env` gitignored.
- A verified connection — `client.admins.list()` returns your workspace admins, confirming the token and API version (**2.11**, applied automatically by the SDK) are correct.

## Error Handling

Common authentication failures and fixes:

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

Catch `IntercomError` to branch on `statusCode` — the full typed pattern is in [error-handling.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/error-handling.md).

## Examples

See [examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/examples.md) for three worked setups: the access-token client (private app, the common path), a connection-verify function with expected output, and an OAuth client (public app).

Minimal working setup:

```typescript
import { IntercomClient } from "intercom-client";

const client = new IntercomClient({ token: process.env.INTERCOM_ACCESS_TOKEN! });
const admins = await client.admins.list();
console.log("Connected! Admins:", admins.admins.length);
```

## Resources

- [OAuth, versioning & scopes](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/oauth.md) — public-app deep dive.
- [Error handling reference](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/error-handling.md) — full error matrix.
- [Worked examples](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/intercom-install-auth/references/examples.md) — copy-paste setups.
- [Authentication Guide](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication)
- [OAuth Scopes](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/oauth-scopes)
- [Setting up OAuth](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth)
- [intercom-client npm](https://www.npmjs.com/package/intercom-client)

## Next Steps

After successful authentication, proceed to the `intercom-hello-world` skill to make your first API call — create a contact, then fetch it back to confirm read and write both work with your configured client.
