Access control
Assign scopes to a plan
Assign your scopes to a plan on its Access Control tab and set each one to Active, Optional, or Restricted.
You assign scopes to a plan on its Access Control tab. For each scope you decide whether every subscriber receives it automatically, can request it, or needs approval. The assignments save with the plan.
Assign the scopes
- Open your product, open the plan, and select the Access Control tab. The plan tabs run Details, APIs, Access Control, Security, Documentation, Limits. The tab appears once scope-based access control is enabled and an authorization server exists.
- In the right-hand column, choose your Authorization Server. Until one is selected you will see "An Authorization Server must be selected before scopes can be configured for this plan."
- The tab lists the scopes for the plan's APIs, grouped by Resource Group. Each scope shows its name, an optional description, and the APIs it is Used by.
- For each scope, set its state with the Active / Optional / Restricted selector:
| State | What the subscriber gets |
|---|---|
| Active | Every subscriber receives this automatically. |
| Optional | Subscribers can request this. |
| Restricted | Requires approval with business justification. |
- Check the Access Summary in the right column to see how many scopes sit in each state. On Amazon Cognito only, a scope-budget bar tracks the 50-scopes-per-client limit; use Group Scopes if you approach it.
- Click Save Changes on the plan. There is no separate save for access control; the assignments are stored with the plan.
After you save, new subscribers receive the Active scopes automatically, and Optional and Restricted scopes become requestable from the API Portal. See Scope grants for the request and approval flow.
Troubleshooting
The Access Control tab tells you what is missing. Match the message to the fix:
| What you see | What to do |
|---|---|
| "No scopes to assign. Select APIs on the APIs tab first." | Add APIs to the plan on its APIs tab. |
| "The selected APIs aren't attached to any scopes yet." | Define scopes on those APIs under Catalog → Resource Groups, then return. |
| "Save the plan first, then assign scopes." | Save the plan once; assignments are stored with it. |
| The tab is read-only, or a banner says the plan has active subscriptions | Access control is locked on a live plan. Create a new plan version to change scope assignments. |
| "Scope-based access control isn't applicable for native-OAuth gateways." | The gateway handles authentication directly, so scopes do not apply to that plan. |