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 holdinggrants: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
New
- A permission refusal answers
403witherror.requiredPermissionnaming 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-sdk3.0.0 and@tangogroup/forge-mcp3.0.0 dropallowedScopesfrom the external-app create and update inputs, exposerequiredPermissiononForgeApiError/PlatformApiError, and deprecaterecordDecision.
Migration
- Stop sending
allowedScopeson 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, readerror.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.

