Toolkits

Get required scopes

Changed on

Experimental: this endpoint is in beta and its contract may change.

Recommends the required scopes to use the given set of tools.

post/api/v3.1/toolkits/{toolkit_slug}/scopes/recommended

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3.1/toolkits/{toolkit_slug}/scopes/recommended
  • Auth
    API key in header x-api-key

Path parameters

toolkit_slugstring required

Toolkit to recommend scopes for.

Request body

toolsstring[] required

Tool slugs to recommend scopes for; an empty list computes the recommendation across all of the toolkit’s tools.

auth_scheme'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'

Auth scheme the connection will use. Defaults to OAUTH2.

toolkit_versionstring

Toolkit version to compute from; defaults to the latest published version. Pass a concrete version to pin.

grant_contextobject

Context in which you want to grant scopes to your user. Pass a dimension and its selected value, for example {"account_type": "Google Workspace"}. Use the List grant contexts endpoint to discover available dimensions and values.

includestring[]

Scopes the recommendation must include, irrespective of usage.

excludestring[]

Scopes the recommendation must not include; the solver picks documented alternatives and fails when none exist.

available_scopesstring[]

Scopes your OAuth app can request. The recommendation never names a scope outside this list and fails with scope_not_available when a tool cannot be covered inside it. Omit for an unbounded recommendation.

Response

Successfully recommended scopes for the requested tools

auth_schemestring required

Auth scheme the recommendation was computed under.

toolkit_versionstring required

Concrete toolkit version the answer was computed from; pass it back as toolkit_version to pin.

grant_contextobject required

The effective grant_context the recommendation was computed with - the toolkit default overlaid with your overrides; {} when none applies.

Changes