Intercom enterprise rbac

Intercom Enterprise RBAC

Overview

Configure enterprise-grade access control for Intercom integrations with OAuth scopes, admin role management, and app-level permission enforcement.

The workflow covers the full path: enumerate the workspace's admins and teams, authorize a public app with least-privilege scopes, enforce per-operation permissions at the application layer, route conversations to teams, and audit sensitive admin actions.

The high-level workflow lives here; complete, copy-ready code for every step is in references/implementation.md, and end-to-end scenarios are in references/examples.md.

Prerequisites

• Intercom workspace with admin access
• Understanding of OAuth 2.0 flows
• For public apps: OAuth configured in Developer Hub
• intercom-client installed and INTERCOM_ACCESS_TOKEN (or OAuth client credentials) available in the environment

Intercom Admin Roles

Intercom has built-in admin roles that control workspace access:

Role	API Access	Capabilities
Owner	Full	All operations, billing, workspace settings
Admin	Full	Manage contacts, conversations, content
Agent	Limited	Reply to conversations, view contacts
Custom roles	Configurable	Enterprise plan feature

These built-in roles govern access inside the Intercom UI and API. Map them onto explicit permissions (Step 3) rather than trusting the role name alone.

Instructions

Follow the five steps in order. Each step's full code is in references/implementation.md under the matching heading — the skeletons below show the essential call surface.

Step 1: List admins and roles

Enumerate every admin and team to map real identities to permissions.

const client = new IntercomClient({ token: process.env.INTERCOM_ACCESS_TOKEN! });
const adminList = await client.admins.list();
// admin.type is "admin" or "team" — teams are used for routing in Step 4

Step 2: OAuth scope-based access control

For public apps, request the minimal scopes required, build the authorization URL with a CSRF state, and exchange the returned code for a per-workspace token.

const authUrl = getAuthUrl(crypto.randomUUID());  // redirect the user here
const { token } = await exchangeCode(code);        // on callback

Store one token per workspace (WorkspaceAuth) for multi-tenant installs. Full exchange + storage code: see references.

Step 3: App-level permission enforcement

Define an explicit IntercomPermission union, map each role to a permission set, and gate operations with middleware — never rely on the role name at the call site.

function checkPermission(role: string, perm: IntercomPermission): boolean { /* … */ }
app.delete("/api/contacts/:id", requirePermission("contacts:delete"), handler);

Step 4: Team-based conversation assignment

Filter admins where type === "team", then assign conversations to the right team by topic via client.conversations.assign(...).

Step 5: Audit logging for admin actions

Record every privileged action to a durable audit store, mirror it as an Intercom data event for visibility, and warn on delete/settings operations.

For the OAuth scope-to-endpoint mapping, see the OAuth Scope Reference table in references/implementation.md.

Output

Applying this skill produces:

• An admin/team inventory printed from client.admins.list() (name, email, id, type).
• A working OAuth authorization + token-exchange flow that yields a per-workspace access token stored as a WorkspaceAuth record.
• A permission layer (ROLE_PERMISSIONS, checkPermission, requirePermission) that returns 403 Forbidden with the missing permission when a caller lacks it.
• Topic-based team routing on conversations.
• Audit entries in the audit store plus mirrored admin-action-logged Intercom data events, with console warnings on sensitive actions.

Error Handling

Issue	Cause	Solution
OAuth callback fails	Wrong redirect URI	Match exactly in Developer Hub
forbidden (403)	Missing OAuth scope	Add scope, user must re-authorize
Token revoked	User uninstalled app	Handle gracefully, notify admin
Admin not found	Admin left workspace	Remove from the local system
Team assignment fails	Team ID invalid	List teams first with admins.list()

Examples

• Gate a delete endpoint by role — only owners reach the handler; agents get a structured 403. See references/examples.md § Example 1.
• Install a public app for a new customer workspace — consent → code exchange → per-workspace token persistence. See § Example 2.
• Route + audit a sensitive assignment in one flow — route to the billing team and record the action. See § Example 3.

Resources

• Authentication
• Setting up OAuth
• OAuth Scopes
• Admins API

Next Steps

For major workspace migrations that move data and reconfigure roles at scale, see the intercom-migration-deep-dive skill, which builds on the RBAC primitives established here.