Resource groups and scopes

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.

A scope reaches a plan through those APIs. A plan's Access Control tab lists every scope attached to at least one of the plan's APIs, so a scope with no APIs never appears on a plan. See Assign scopes to a plan.

How do you add scopes?

From the Resource Groups page, in four ways: by hand, from a file, from your Authorization Server, or with the Scope Creation Wizard.

How do you create a resource group by hand?

Choose New Group, name it, and save. Then add scopes to the group and attach each one to its APIs.

1. Open Catalog, then Resource Groups.
2. Choose New Group.
3. Enter a name for the group and click Save Changes.
4. Add scopes to the group, each with a name and an optional description.
5. Attach each scope to the APIs it protects, as described below.

How do you attach a scope to APIs?

In the scope's edit form, or from the API's side in the API Catalog. Until a scope has APIs, it does not appear on any plan.

• From the scope: on the Resource Groups page, click Edit on the scope, tick the APIs it applies to, and save.
• From the API: open the API under Catalog → API Catalog, go to its Scope Assignments tab, tick the scopes, and click Save Changes.

How do you import resource groups from a file?

Choose Import/Export, stay on the Import tab, download a template, fill it in, and upload it. The dialog previews every group and flags issues before anything is created.

1. Choose Import/Export. The dialog opens on the Import tab.
2. Under Download a template:, choose CSV, JSON, or YAML.
3. Fill in your groups and scopes. In CSV, write one scope per row. Rows with the same group_name form one group.
4. Upload the file. The dialog previews each group with its scopes and flags any issues.
5. Click the import button. It reads Import {count} groups, or Import {count} valid groups when some groups have warnings.

The CSV template has one row per scope, with these columns:

What import issues might the preview flag?

The preview labels each problem. Two issues block the import. The other three are warnings.

When any group has a blocking error, the button reads Fix errors to import and stays disabled.

How do you export your scopes?

Choose Import/Export, open the Export tab, and click Export Scopes. Pick Download as CSV, Download as JSON or Download as YAML. The file holds every scope across every resource group.

Every format uses the same four fields as the CSV template: group_name, scope_name, scope_description and api_ids. In an export, several API IDs are separated by a vertical bar (|). A plan's Access Control tab has its own Export Scopes button for just that plan's scopes.

Use an export to hand your scope list to an Authorization Server that Apiable cannot write to, such as Auth0 or Duende IdentityServer.

How does Sync with Auth Server work?

It compares Apiable's scopes with a connected Authorization Server and moves the difference in one direction. Pull brings server scopes into Apiable. Push sends Apiable's scopes to the server, which creates them on Keycloak only.

1. Choose Sync with Auth Server. The button appears once an Authorization Server has passed Test Connection with status Connected, and the dialog names the server it works with.
2. Choose Pull from Auth Server or Push to Auth Server.
3. Review the preview: Only in Apiable, Only on Auth Server, and In sync.
4. Click Confirm Pull or Confirm Push, or Back to choose again.

What each direction does:

Pulled scopes are grouped by the prefix before :, . or /. When two or more pulled scopes share a prefix, they go into a group named after it, capitalized. Other scopes go into a group named Default. If a group with that name exists, the scopes are added to it.

On Keycloak, Only on Auth Server includes the realm's built-in client scopes, and Pull imports them too. Check the preview before you confirm. Sync does not work with Duende IdentityServer, because Apiable cannot read or write scopes there.

How does the Scope Creation Wizard work?

The Scope Creation Wizard reads your API Catalog and proposes resource groups and scopes for the APIs you choose. You review and edit the proposal, then create the groups, with each scope already attached to its APIs. It runs four steps under a per-account daily quota.

1. Check. The wizard shows the APIs in your catalog. Choose Generate for all {count} APIs, or Select APIs to include and pick them, with search. If the catalog is empty, it offers Sync catalog to pull your gateways' APIs first.
2. Naming. Choose a naming pattern for the generated scopes, resource:verb or resource.verb.
3. Preview. The wizard proposes resource groups and scopes, which you can edit before continuing.
4. Create. The wizard creates the resource groups and reports which succeeded.

You can also open the wizard from the Run AI Wizard → hint on the Resource Groups page. When the quota runs out, the wizard shows Daily quota reached. Try again the next day or contact support.

What happens when you rename or delete a scope that plans use?

Apiable shows which plans use the scope before it changes anything, and blocks the change while one of those plans has active subscriptions. After a rename, review the scope's state on each of those plans.

• Rename scope lists the affected plans. Confirm with Rename & propagate. On those plans, the renamed scope then shows at the starting state, Active. Review it on each plan's Access Control tab, and change it if it should be Optional or Restricted.
• Delete scope lists the affected plans. Type the scope's name, then confirm with Delete scope. The scope no longer appears on those plans' Access Control tabs.
• If a plan that uses the scope has active subscriptions, the dialog blocks the change. Create a new version of that plan first.

Why can I not delete a resource group?

A resource group that is used by one or more plans cannot be deleted. The delete dialog says how many plans use it, and offers only Close.

Remove the group from those plans first, then delete it. The same rule applies when you delete several groups at once: the groups in use are listed and nothing is deleted.

Where to next