---
title: "List grant contexts"
method: GET
path: "/api/v3.1/toolkits/{toolkit_slug}/scopes/grant_context"
tags: ["Toolkits"]
---

# List grant contexts

`GET /api/v3.1/toolkits/{toolkit_slug}/scopes/grant_context`

## Request

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

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

List of contexts in which you want to grant scopes to your user. Pass a dimension and its selected value in the `grant_context` field of the [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) request to tailor the scope recommendation.

In the Jira example, `default_grant_context` is `{"scope_family": "classic"}`, so a recommendation with no `grant_context` uses classic scopes. Pass `{"scope_family": "granular"}` to get granular scopes instead.

## Path parameters

- `toolkit_slug` string, required: Toolkit to list grant contexts for.

## Query parameters

- `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 read the catalog from; defaults to the latest published version. Pass a concrete version to pin.

## Response `200`

Successfully discovered the toolkit's grant-context dimensions

- object
  - `auth_scheme` string, required: Auth scheme whose scope catalog the vocabulary was read from.
  - `toolkit_version` string, required: Concrete toolkit version the answer was computed from; pass it back as toolkit_version to pin.
  - `grant_context_dimensions` object[], required: Dimensions this toolkit accepts in grant_context under the auth scheme; [] when no scope depends on grant_context.
    - `dimension` string, required: Context in which you could grant scopes to your user.
    - `description` string, required: What this dimension means and when to pass it.
    - `values` string[], required: Values that this dimension can take.
  - `default_grant_context` object, required: The grant_context assumed when you pass none — pass a dimension and its selected value only to override or extend it.

## Other responses

- `400`: Bad request (validation_error: auth_scheme outside the platform enum or not defined by the toolkit)
- `401`: Unauthorized
- `404`: Toolkit or toolkit_version not found
- `500`: Internal server error

## 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/grant_context/get.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)