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

# 2026-09-26 — Breaking: API keys and External Apps act on role grants; scopes only narrow

> An API key or External App acts on its role grants. Scopes only narrow them, a 403 names the missing permission, allowedScopes is read-only, and no key or app can approve.

**2026-09-26**

Breaking: keys and apps act on role grants. Scopes only narrow, a 403 names the missing permission, allowedScopes is read-only, and approvals need a person.

## Summary

An API key and an External App are now **actors**, like a person. What they may do is the **role grants** they hold, given in the Forge Console by someone holding `grants:manage`. A key's `scopes`, and an access token's `scope`, no longer grant anything: they only narrow what the actor's roles allow. The published scope names are unchanged. See [Permissions and scopes](https://docs.gloo.com/forge/reference/conventions.md#permissions-and-scopes).

Existing keys and apps keep working: each active one that held scopes was given a compatibility role holding exactly the permissions its scopes mapped to.

## Breaking changes

> [!WARNING]
>
> **A new key or app holds no roles.** `POST /api/v2/externalApps/create` and a new Forge MCP API key both start with no roles, so every call they make is refused until someone gives them roles in the Forge Console.

> [!WARNING]
>
> **`allowedScopes` is read-only.** `POST /api/v2/externalApps/create` and `PATCH /api/v2/externalApps/update` answer `400` with code `allowed_scopes_removed` when the body carries `allowedScopes` (on update, an empty list included). On `get` and `GET /api/v2/me` it is computed: the published scopes whose every permission the app's roles hold. `list` no longer returns it.

> [!WARNING]
>
> **No key or app can approve.** `approvals:approve` (scope `governance:write:approve`) and `apikeys:manage` (scope `keys:manage`) are never held by a key or an app. `POST /api/v2/governance/recordDecision` answers `403` for every Door B caller; approve as a person in the Forge Console.

> [!WARNING]
>
> **The inference file routes need `inference:use`.** `/api/inference/v1/files`, `/files/confirm`, `/files/get` and `/files/delete` require `inference:use` (scope `inference:app`). A token carrying only `files:read` or `files:write` now receives `403` there. Those scopes apply to `/api/v2/files` and `/api/v2/files/content`.

## New

* A permission refusal answers `403` with `error.requiredPermission` naming the catalog permission the caller lacks.
* The OpenAPI spec (0.7.0) states each operation's required permissions (`x-forge-permissions`) and the scope that narrows to them (`x-forge-published-scope`).
* `@tangogroup/forge-sdk` 3.0.0 and `@tangogroup/forge-mcp` 3.0.0 drop `allowedScopes` from the external-app create and update inputs, expose `requiredPermission` on `ForgeApiError` / `PlatformApiError`, and deprecate `recordDecision`.

## Migration

* Stop sending `allowedScopes` on external-app create and update. Give the app roles instead.
* After creating an app or an MCP key, give it roles before first use.
* On a `403`, read `error.requiredPermission`: give the actor a role holding it, or request a token with the scope that maps to it.
* Move approval decisions to a person.


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