Skip to content
Ascend GTM Ops — Docs

Composio Scope Gaps — What They Are and How We Fix Them

Composio Scope Gaps — What They Are and How We Fix Them

What is a scope gap?

A scope gap occurs when a Composio-managed OAuth connection exists and is authenticated, but the OAuth app that backs the connection was granted fewer scopes than a particular API endpoint requires.

Symptoms:

  • HTTP 403 from a Composio tool call
  • Error body mentions insufficient_scope, requires_scope, or lists specific missing permissions
  • The connection shows as ACTIVE in Composio’s dashboard, but the tool call fails

What it is NOT:

  • Toolkit-not-found (404 on the toolkit slug) — see missing-toolkit-runbook.md
  • Provider-side permission error (e.g. HubSpot portal settings, Salesforce profile-level access) — this is a scope gap only if it’s an OAuth grant problem
  • Expired connection — Composio handles token refresh; an expired-and-not-refreshable connection shows as DISCONNECTED, not 403

Why it happens

By default, Composio registers OAuth apps with a common scope set that covers most tools. When Ascend uses a tool that requires a scope outside that default set, the connection’s access token doesn’t include the right permission and the provider returns 403.

This is especially common for:

  • Write operations that weren’t anticipated at initial connect time
  • Admin-scoped endpoints (HubSpot admin, Salesforce setup objects, Google Workspace admin)
  • New API features a provider added scopes for recently

How it gets fixed

See .claude/skills/composio/scope-gap-resolver/SKILL.md for the step-by-step runbook.

Summary:

  1. Register a BYO OAuth app in the provider’s developer console with the full scope set (existing + missing)
  2. Store client_id / client_secret in Infisical
  3. Create a custom auth config in Composio (SDK-based: composio.authConfigs.create())
  4. Re-run OAuth connect so the user grants the new scopes
  5. Record in auth-config-registry.md

Key constraint: The OAuth redirect URI must be https://backend.composio.dev/api/v3.1/toolkits/auth/callback (Composio-owned, verify from docs before use).

Registry

All resolved scope gaps are recorded in auth-config-registry.md. Check there first — if a BYO auth config already exists for the provider, the fix may be as simple as re-running the connect flow.

Escalation

If the 403 persists after a correctly-scoped BYO auth config is in place:

  1. Verify the provider’s docs — the required scope may have changed
  2. Check if the provider requires app review/approval for elevated scopes (common for Google, Salesforce)
  3. Contact Composio support if the auth config creation itself is failing