API ReferenceToolkits

Get required scopesv3.1

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

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

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

Authorization

ApiKeyAuth
x-api-key<token>

Project API key authentication

In: header

Path Parameters

toolkit_slugstringRequired

Toolkit to recommend scopes for.

Request Body

application/json

toolsarray of stringRequired

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

auth_schemeenum

Auth scheme the connection will use. Defaults to OAUTH2.

Default: "OAUTH2"
Possible values:
OAUTH2OAUTH1API_KEYBASICBILLCOM_AUTHBEARER_TOKENGOOGLE_SERVICE_ACCOUNTNO_AUTHBASIC_WITH_JWTCALCOM_AUTHSERVICE_ACCOUNTSAMLDCR_OAUTHCIMD_OAUTHS2S_OAUTH2
toolkit_versionstring

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

Default: "latest"
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.

includearray of string

Scopes the recommendation must include, irrespective of usage.

excludearray of string

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

available_scopesarray of 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 Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3.1/toolkits/string/scopes/recommended" \  -H "Content-Type: application/json" \  -d '{    "tools": [      "GOOGLECALENDAR_EVENTS_LIST",      "GOOGLECALENDAR_CREATE_EVENT"    ]  }'
{  "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"        ]      }    ]  }}
Edit this page on GitHub