Skip to main content
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.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

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.
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.
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.
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.