> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get required scopes

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

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



## OpenAPI

````yaml api-reference/openapi.json POST /api/v3.1/toolkits/{toolkit_slug}/scopes/recommended
openapi: 3.1.0
info:
  version: 3.1.0
  title: Composio Platform API v3.1
  description: >-
    Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints
    default to the latest tool version.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/toolkits/{toolkit_slug}/scopes/recommended:
    post:
      tags:
        - Toolkits
      summary: Get required scopes
      description: |-
        Experimental: this endpoint is in beta and its contract may change.

        Recommends the required scopes to use the given set of tools.
      operationId: recommendToolkitScopes
      parameters:
        - schema:
            type: string
            minLength: 1
            description: Toolkit to recommend scopes for.
          required: true
          description: Toolkit to recommend scopes for.
          name: toolkit_slug
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tools:
                  type: array
                  items:
                    type: string
                  description: >-
                    Tool slugs to recommend scopes for; an empty list computes
                    the recommendation across all of the toolkit’s tools.
                auth_scheme:
                  type: string
                  enum:
                    - 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
                  default: OAUTH2
                  description: Auth scheme the connection will use. Defaults to OAUTH2.
                toolkit_version:
                  type: string
                  minLength: 1
                  default: latest
                  description: >-
                    Toolkit version to compute from; defaults to the latest
                    published version. Pass a concrete version to pin.
                grant_context:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    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](/reference/api-reference/toolkits/recommendToolkitScopesGrantContext)
                    endpoint to discover available dimensions and values.
                include:
                  type: array
                  items:
                    type: string
                  description: >-
                    Scopes the recommendation must include, irrespective of
                    usage.
                exclude:
                  type: array
                  items:
                    type: string
                  description: >-
                    Scopes the recommendation must not include; the solver picks
                    documented alternatives and fails when none exist.
                available_scopes:
                  type: array
                  items:
                    type: string
                  description: >-
                    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.
              required:
                - tools
              x-experimental: true
            examples:
              googlecalendar:
                summary: 'Google Calendar: list and create events'
                value:
                  tools:
                    - GOOGLECALENDAR_EVENTS_LIST
                    - GOOGLECALENDAR_CREATE_EVENT
      responses:
        '200':
          description: Successfully recommended scopes for the requested tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_scheme:
                    type: string
                    description: Auth scheme the recommendation was computed under.
                  toolkit_version:
                    type: string
                    description: >-
                      Concrete toolkit version the answer was computed from;
                      pass it back as toolkit_version to pin.
                  grant_context:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      The effective grant_context the recommendation was
                      computed with - the toolkit default overlaid with your
                      overrides; {} when none applies.
                  scopes:
                    type: object
                    properties:
                      least_privilege:
                        type: array
                        items:
                          type: string
                        description: Narrowest documented option per requirement.
                      fewest:
                        type: array
                        items:
                          type: string
                        description: Smallest scope set covering all requirements.
                      conditional:
                        type: array
                        items:
                          type: object
                          properties:
                            scope:
                              type: string
                              description: The scope needed only under the `when` guard.
                            when:
                              type: object
                              additionalProperties:
                                type: array
                                items:
                                  type: string
                              description: >-
                                Condition for when this scope is needed: input
                                field name to qualifying values (any value
                                matches within a field; all fields must match).
                            for:
                              type: array
                              items:
                                type: string
                              description: Tool slugs that need this scope under the guard.
                          required:
                            - scope
                            - when
                            - for
                        description: >-
                          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.
                    required:
                      - least_privilege
                      - fewest
                      - conditional
                required:
                  - auth_scheme
                  - toolkit_version
                  - grant_context
                  - scopes
                x-experimental: true
              examples:
                googlecalendar:
                  summary: 'Google Calendar: list and create events'
                  value:
                    auth_scheme: OAUTH2
                    toolkit_version: 20260915_00
                    grant_context: {}
                    scopes:
                      least_privilege:
                        - >-
                          https://www.googleapis.com/auth/calendar.calendars.readonly
                        - https://www.googleapis.com/auth/calendar.events
                      fewest:
                        - https://www.googleapis.com/auth/calendar
                      conditional:
                        - scope: >-
                            https://www.googleapis.com/auth/calendar.calendars.readonly
                          when:
                            param.eventType:
                              - default
                            param.exclude_organizer:
                              - falsy
                          for:
                            - GOOGLECALENDAR_CREATE_EVENT
        '400':
          description: >-
            Bad request (validation_error, action_not_available,
            grant_context_required, not_available_in_grant_context)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Toolkit or toolkit_version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Exclusions or the available_scopes ceiling leave a requested tool
            with no grantable scope (exclude_conflict, scope_not_available)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: >-
            Some requested tools are not supported by scope resolution yet
            (not_supported)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key

````