---
title: "Get required scopes"
method: POST
path: "/api/v3.1/toolkits/{toolkit_slug}/scopes/recommended"
tags: ["Toolkits"]
---

# Get required scopes

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

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

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

## Path parameters

- `toolkit_slug` string, required: Toolkit to recommend scopes for.

## Request body

- object
  - `tools` string[], 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_version` string: Toolkit version to compute from; defaults to the latest published version. Pass a concrete version to pin.
  - `grant_context` object: 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](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopesGrantContext) endpoint to discover available dimensions and values.
  - `include` string[]: Scopes the recommendation must include, irrespective of usage.
  - `exclude` string[]: Scopes the recommendation must not include; the solver picks documented alternatives and fails when none exist.
  - `available_scopes` string[]: 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 `200`

Successfully recommended scopes for the requested tools

- object
  - `auth_scheme` string, required: Auth scheme the recommendation was computed under.
  - `toolkit_version` string, required: Concrete toolkit version the answer was computed from; pass it back as toolkit_version to pin.
  - `grant_context` object, required: The effective grant_context the recommendation was computed with - the toolkit default overlaid with your overrides; {} when none applies.
  - `scopes` object, required
    - `least_privilege` string[], required: Narrowest documented option per requirement.
    - `fewest` string[], required: Smallest scope set covering all requirements.
    - `conditional` object[], required: Scopes needed only for particular call-time inputs; the lists above already include them worst-case, so a caller that knows its inputs may subtract the rest. Empty when none apply.
      - `scope` string, required: The scope needed only under the `when` guard.
      - `when` object, required: Condition for when this scope is needed: input field name to qualifying values (any value matches within a field; all fields must match).
      - `for` string[], required: Tool slugs that need this scope under the guard.

## Other responses

- `400`: Bad request (validation_error, action_not_available, grant_context_required, not_available_in_grant_context)
- `401`: Unauthorized
- `404`: Toolkit or toolkit_version not found
- `422`: Exclusions or the available_scopes ceiling leave a requested tool with no grantable scope (exclude_conflict, scope_not_available)
- `500`: Internal server error
- `501`: Some requested tools are not supported by scope resolution yet (not_supported)

## Changes

- **2026-10-16** `98956f31abf3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/changes/api/v3.1/toolkits/:toolkit_slug/scopes/recommended/post.md)

---

[API](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1.md) - [All operations](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/llms.txt) - [OpenAPI document](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/revisions/4bd56a0836f8?raw)