> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fmgsuite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding scopes

> What to do when your app needs a scope that an existing connection has not granted.

When FMG grants your app a new scope, existing connections do not receive it. A user approves scopes when they authorize your app, and their tokens only ever carry the scopes they approved. Refreshing a token does not add scopes: a `scope` parameter on the refresh request is ignored, and the response carries the original set.

To use a new scope, the user must **re-authorize** your app. Until they do, their existing connection keeps working with the scopes it already has.

## Check what a connection has

The token response lists the granted scopes:

```json theme={null}
{
  "access_token": "eyJ...",
  "refresh_token": "v2.abc...",
  "scope": "openid offline_access fmg.content.read"
}
```

Store `scope` with the tokens and compare it to what a feature needs before calling the API.

## The error when a scope is missing

Calling an endpoint without its required scope returns `403`:

```json theme={null}
{
  "type": "https://developers.fmgsuite.com/problems/forbidden",
  "title": "Forbidden.",
  "status": 403,
  "detail": "Access token is missing required scope 'fmg.contacts.read'.",
  "instance": "/v1/fmg/contact/contacts",
  "code": "forbidden",
  "traceId": "b7f4bd62-2790-48fd-ba93-29552d6d15a6",
  "retryable": false
}
```

`detail` names the missing scope. The request is not retryable: the same token fails until the user re-authorizes.

## Re-authorize

Run the authorization flow again from Step 1 of the [OAuth guide](https://developers.fmgsuite.com/fmg/oauth/client-integration.md), requesting the **full** scope list: the scopes already granted plus the new one. The user is asked to approve the added scope. Replace the stored tokens with the ones from the new token exchange.

> [!NOTE]
>
> Request only scopes FMG has enabled for your app. Requesting any other scope redirects back to your `redirect_uri` with `error=invalid_scope`.

## Prompting the user

Use one or more of these, depending on how your app is built.

**Notify ahead of time.** When you release a feature that needs a new scope, tell affected users by email or in-app message: what the feature does, what the new permission allows, and a link that starts re-authorization.

**Offer a reconnect option.** While a connection is missing a scope your app uses, show an "Update permissions" or "Reconnect" action on your integration settings page, with one line explaining what it enables.

**Ask at the moment of use.** When a user opens a feature whose scope is missing, or a call returns `403` naming the scope, explain that the feature needs an additional permission, start re-authorization, and return the user to the action when it completes.

> [!WARNING]
>
> Do not start re-authorization without telling the user why, and do not repeat it after the user declines. A user who denies consent is redirected with `error=access_denied`; keep their existing connection and offer the option again later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.