> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/custom-oauth-scopes-and-reauthorization.md).

# Custom OAuth scopes and reauthorization

OAuth scopes define the permissions that an account grants to an application. Use custom scopes to request the access required by your selected actions.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fu4VIT0l84EEJcu7grGrd%2FG048A.mp4?alt=media&token=46e5baf1-68a7-47ba-b1ba-7dc129f8041e>" %}

## Before you start

Have permission to edit the custom connector and know which action requires a new permission. Identify affected account connections using [Provider connector configuration](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/provider-connector-configuration.md). Ask the connector administrator to make the change if you cannot open its Configuration.

## Review and select scopes

Open the custom connector's Configuration and inspect its OAuth scopes.

![OAuth scope compatibility settings](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/HTeYOrUFdgLW4gwLtJGa/assets/g048a-g048a-01-edit.png)

These scopes define the provider permissions the connector requests during authorization.

Select the required scope and review action compatibility.

![OAuth scope compatibility settings](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/9waeo8PGAsUQfHS6Rsfx/assets/g048a-g048a-02-compatibility.png)

An action that sends or changes data may require permissions beyond a read-only scope.

## Save the scope configuration

Save the selected scopes.

![Saved OAuth scope configuration](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/TE5e0D0HnyyNvNtXHCRL/assets/g048a-g048a-03-save.png)

Actions that require other scopes may remain unavailable.

## Reauthorize affected accounts

Reconnect the affected account so its authorization reflects the required scopes.

![Provider account reauthorization flow](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/fPHuYdyuKZ6Us3uVllA0/assets/g048a-g048a-04-reauthorize.png)

Review the provider's consent screen to confirm the actual requested access.

Return to Connections and check the refreshed account's health.

![Provider account reauthorization flow](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/FcJjCvECT8BhgLaoqNYc/assets/g048a-g048a-05-health.png)

Then verify the operation for which the scope change was made.

## Check the required operation

Run the action that needs the updated permission.

![Action execution after reauthorization](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/49fRY12gMHO6JoxeGhx4/assets/g048a-g048a-06-test.png)

Inspect the response or error to check whether the provider granted the required access.

## Request additional scopes when needed

Add a broader scope only when an intended operation requires it.

![Additional OAuth scope selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/S8LySm2ibtwscjlmGyX5/assets/g048a-g048a-07-preview-only.png)

Reconnect affected accounts after changes that require new provider consent.

## Important behavior

OAuth scopes specify the access requested from the provider. Enabling an action in StackAI cannot substitute for a missing provider permission.

## Continue

* [Create and manage connections](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/create-and-manage-connections.md)
* [Configure and test an action](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/configure-and-test-an-action.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/custom-oauth-scopes-and-reauthorization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
