Access control
Resource groups and scopes
Organize your OAuth2 scopes into resource groups. Create them by hand, by CSV, JSON, or YAML import, or with the Scope Creation Wizard that reads your API Catalog.
A resource group is a named collection of scopes. You organize your OAuth2 scopes into resource groups so related scopes, for example all the scopes for one API, are managed together. You find them under Catalog, then Resource Groups.
What is a resource group?
A resource group has a name and a list of scopes. Each scope has a name, an optional description, and the catalog APIs it applies to. Grouping scopes lets you import, edit, and assign them together rather than one at a time.
The Resource Groups page lists each group with its scopes, and shows the total number of scopes across all groups. You assign these scopes to a plan on the plan's Access Control tab. See Assign scopes to a plan.
How do I create resource groups?
There are three ways, all from the Resource Groups page. Create one by hand, import many at once from a file, or let the Scope Creation Wizard propose them from your catalog.
| Method | Button | Best for |
|---|---|---|
| By hand | New Group | A single group you define yourself. |
| Import | Import CSV | Bulk loading groups and scopes from CSV, JSON, or YAML. |
| Wizard | Create with Wizard | A first set of scopes proposed from your API Catalog. |
There is also a Sync from Auth Server action, which reads scopes that already exist on a connected authorization server.
How do I create a resource group by hand?
Choose New Group, name it, and save. You then add scopes to the group from the list.
- Open Catalog, then Resource Groups.
- Choose New Group.
- Enter a name for the group.
- Click Save Changes.
- Add scopes to the group, each with a name and an optional description.
How do I import resource groups from a file?
Choose Import CSV, download a template, fill it in, and upload it. The import accepts CSV, JSON, or YAML, and previews every row before it commits.
- Choose Import CSV to open the import dialog.
- Download the CSV, JSON, or YAML template.
- Fill in your groups and scopes, one scope per row in CSV.
- Upload the file. The dialog previews the rows and flags any issues.
- Confirm the import.
The CSV template has one row per scope, with these columns:
| Column | What it holds |
|---|---|
group_name | The resource group the scope belongs to. |
scope_name | The scope name. |
scope_description | An optional description of the scope. |
api_ids | The catalog API IDs the scope applies to. |
What import issues might the preview flag?
The preview checks each row and labels any problems. Two issues are errors that block the import; the rest are warnings that let you proceed but may overwrite existing data.
| Issue | Shown as | Meaning | Blocks import |
|---|---|---|---|
invalid-name | Invalid name | The group name is empty. | Yes |
no-scopes | No scopes | The group has no scopes. | Yes |
duplicate-in-file | Duplicate in file | The same group name appears more than once in the file. | No |
duplicate-existing | Already exists | A group with this name already exists in your account. | No |
duplicate-scopes | Duplicate scopes | The same scope name appears more than once within the group. | No |
When any row has a blocking error, the confirm button reads Fix errors to import and stays disabled. When only warnings remain, you can import the valid groups.
How does the Scope Creation Wizard work?
The Scope Creation Wizard reads your API Catalog and proposes resource groups and scopes for your APIs. You review and edit the proposal, then create the groups. It runs four steps and is subject to a per-account daily quota.
- Check. The wizard counts the APIs in your catalog. If the catalog is empty, it offers to sync your gateways first.
- Naming. You choose a naming pattern for the generated scopes, for example
resource:verborresource.verb. - Preview. The wizard generates a proposed set of resource groups and scopes, which you can edit before continuing.
- Create. The wizard creates the resource groups and reports which succeeded.
Why can I not delete a resource group?
A resource group that is used by one or more plans cannot be deleted. The delete confirmation stays disabled and tells you how many plans use it.
Remove the group from those plans first, by changing their scope assignments, then delete the group. The same rule applies when you delete several groups at once: any that are in use are listed and blocked.