---
canonical_url: "https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopesGrantContext"
markdown_url: "https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopesGrantContext.md"
product: "platform"
version: "3.1"
last_updated: null
---

# List grant contexts

**Documentation:** /reference/api-reference/toolkits/recommendToolkitScopesGrantContext

> **API version:** This page documents Composio REST API v3.1, the current version, at `https://backend.composio.dev/api/v3.1`. `https://backend.composio.dev/api/v3` is the previous version and remains supported.

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.

---

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

**Endpoint:** `https://backend.composio.dev/api/v3.1/toolkits/{toolkit_slug}/scopes/grant_context`

**Summary:** List grant contexts

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.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key`

### Path Parameters

- `toolkit_slug` (string) *(required)*: Toolkit to list grant contexts for.

### Query Parameters

- `auth_scheme` (enum: "OAUTH2" | "OAUTH1" | "API_KEY" | ...): 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.

### Responses

#### 200 - Successfully discovered the toolkit's grant-context dimensions

**Response Schema:**

- `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` (array<object>) *(required)*: Dimensions this toolkit accepts in grant_context under the auth scheme; [] when no scope depends on grant_context.
  - Array items:
    - `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` (array<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.
  - `[key: string]` (string)

**Example Response:**

```json
{
  "auth_scheme": "string",
  "toolkit_version": "string",
  "grant_context_dimensions": [
    {
      "dimension": "string",
      "description": "string",
      "values": [
        "..."
      ]
    }
  ],
  "default_grant_context": {
    "key": "string"
  }
}
```

#### 400 - Bad request (validation_error: auth_scheme outside the platform enum or not defined by the toolkit)

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Toolkit or toolkit_version not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X GET "https://backend.composio.dev/api/v3.1/toolkits/string/scopes/grant_context" \
  -H "x-api-key: YOUR_API_KEY"
```

---

## REST API version

The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples.

`https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate.