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. Every scope starts as Active.
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.
How do you assign scopes to a plan?
Open the plan's Access Control tab, confirm the Authorization Server, set each scope to Active, Optional or Restricted, and click Save Changes. Every scope starts as Active.
- Open your product, open the plan, and select the Access Control tab. The plan tabs run Details, APIs, Access Control, Security, Documentation, Limits, and more. The tab appears once scope-based access control is on and at least one Authorization Server exists.
- Confirm the Authorization Server. When none is selected yet, the tab shows Select an Authorization Server with the note "An Authorization Server must be selected before scopes can be configured for this plan." and a picker. Apiable selects it for you when your account has only one server, or when the plan's gateway sets a default. A gateway that locks its pairing shows the server read-only, marked Locked by gateway "{name}".
- The tab lists the scopes attached to the plan's APIs, grouped by Resource Group. Each scope shows its name, an optional description, and the APIs it is Used by.
- Set each scope's state with the Active / Optional / Restricted selector. Every scope starts as Active, which means every subscriber receives it. Change any scope you don't want every subscriber to receive.
- Check the Access Summary in the right column to see how many scopes sit in each state.
- 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.
What does each state give a subscriber?
The state decides whether a subscriber gets the scope at once, can ask for it, or must justify the request.
| State | What the subscriber gets |
|---|---|
| Active | Every subscriber receives this automatically. |
| Optional | Subscribers can request this. |
| Restricted | Requires approval with business justification. |
What if the plan uses scopes your Authorization Server does not have?
The tab warns you: "This plan references {count} scope(s) not on {server}.", followed by the missing scope names. New subscribers do not get those scopes until they exist on the server.
- Sync with Auth Server in the warning pushes the missing scopes. This creates them on Keycloak only.
- Export Scopes beside it downloads the plan's scopes, so you can add them to your server by hand. Use it for Auth0.
- Saving the plan is not blocked.
On Duende IdentityServer, Apiable cannot read your scopes, so this warning does not appear. Check the list yourself.
How do you export a plan's scopes?
Click Export Scopes at the top of the tab and choose Download as CSV, Download as JSON or Download as YAML. The file lists the scopes attached to the plan's APIs, with their resource group, description and API IDs.
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. Configure scopes on their Resource Groups, then return here." | Attach scopes to those APIs: in the scope's edit form under Catalog → Resource Groups, or on the API's Scope Assignments tab in the API Catalog. Then return. |
| "Save the plan first, then assign scopes." | Save the plan once. Assignments are stored with it. |
| "Scope-based access control isn’t applicable for native-OAuth gateways. Authentication is handled by the gateway directly.", or the Authorization Server shows Not applicable | The plan's gateway handles OAuth itself. On the gateway's Authorization tab, choose Authorization Server under What handles OAuth flows?, pick a server, and click Save Changes. |
| Cross-gateway lock conflict | The plan's APIs come from gateways locked to different Authorization Servers. Adjust the API selection on the APIs tab before configuring access control. |
| Locked by gateway "{name}" under the Authorization Server | The gateway's Product-level governance is Locked to this pairing. Change the server on that gateway's Authorization tab, or keep it. |
| Some APIs have no scopes assigned | The APIs listed under the note have no scopes attached. Attach scopes to them, or leave them if they need none. |
| "This plan references {count} scope(s) not on {server}." | See What if the plan uses scopes your Authorization Server does not have? |
| This version has active subscriptions, and the tab is read-only | Access control is locked on a live version. Create a new plan version to change scope assignments. Existing subscribers stay on the current version. |
| No Access Control tab on the plan | Scope-based access control is not on for your account, or no Authorization Server exists yet. |