> ## 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 an MRC scope that an existing connection has not granted.

When FMG grants your app a new `mrc.*` scope, existing connections do not receive it. An advisor 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 advisor 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 mrc.messaging.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`. For example, sending a message with a token that lacks `mrc.messaging.write`:

```json theme={null}
{
  "type": "https://developers.fmgsuite.com/problems/forbidden",
  "title": "Forbidden.",
  "status": 403,
  "detail": "Access token is missing required scope 'mrc.messaging.write'.",
  "instance": "/v1/mrc/messaging/messages",
  "code": "forbidden",
  "traceId": "1c95b936-ca30-4dfd-8627-e7e8b9280950",
  "retryable": false
}
```

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

## Re-authorize

Run the authorization flow again from Step 1 of the [OAuth guide](https://developers.fmgsuite.com/mrc/oauth/client-integration.md), requesting the **full** scope list: the scopes already granted plus the new one. The advisor 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 advisor

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 advisors 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 an advisor 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 advisor to the action when it completes.

> [!WARNING]
>
> Do not start re-authorization without telling the advisor why, and do not repeat it after the advisor declines. An advisor 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.