Scopes

The Scopes module centralizes the authorization scopes used by AI Gateway. Each scope is a named label, with an optional description, that can be referenced by one or more Routes, MCP Servers, and AI Agents. The gateway uses these scopes to determine who can access each resource by comparing the scopes in the presented token with the scopes required by the resource.

NOTE

Scopes is the canonical place to describe authorization in AI Gateway. Instead of typing free-form strings in each Route, MCP Server, or AI Agent, you register the scope here once and reference the scope ID in the forms for the other features. Renaming a scope here propagates the new name to every resource that uses it.

Quick links

Learn how to:

• Filter and list Scopes
• Create a Scope
• View Scope relationships
• Edit a Scope
• Delete a Scope
• Review the form fields

Listing

The Scopes page lists registered scopes with pagination. You can filter by:

• Search scopes (optional): text search by scope name.

Use Search to apply the filter and Clear to reset it.

Columns shown in the table:

• Name: scope name.
• Description: scope description (displays - when empty).
• Routes: list of Routes that reference this scope (shows No relationships. when empty).
• MCP Servers: list of MCP Servers that reference this scope (shows No relationships. when empty).
• AI Agents: list of AI Agents that reference this scope (shows No relationships. when empty).
• Actions: Overview (magnifying glass) and Delete icons for each row.

Create Scope

After creation, the gateway-generated scope ID becomes available in the scope selects in the Routes, MCP Servers, and AI Agents forms.

View Scope (Overview)

In the Actions column of the row you want, click the Overview icon (magnifying glass). A read-only screen opens at /scopes/<scopeId>/view with:

• Name and Description for the scope.
• Three Connected entities tabs: Routes, MCP Servers, and AI Agents. They list every resource that references this scope, with Display name, Owner ID, and Authorization Policy Target ID columns.
• Edit button (pencil icon) to open the edit form.

Use Overview when you need to check the impact of changing or deleting a scope before taking action.

Edit Scope

In the Actions column of the row you want, click the Overview icon and then the Edit button. You can also open /scopes/<scopeId>/edit directly. The Update Scope form opens with the current data and shows the same Connected entities tabs described in View Scope below the editable fields.

CHANGES PROPAGATE AUTOMATICALLY

When the scope is already in use, the form displays the warning "This scope is already in use. Changing its name will update it everywhere it is used." Changing the Name immediately updates every resource that references this scope. Check the Connected entities list before confirming.

Change the required fields and click Save.

Delete Scope

In the Actions column of the row you want, click the Delete icon. Confirm the operation in the "Do you want to delete scope [scopeId]?" dialog.

IMPORTANT

Deletion is permanent and cannot be undone. If any Routes, MCP Servers, or AI Agents are associated with this scope, remove those associations first and then delete it. Open the scope Overview to identify dependent resources.

Form fields

The table below covers all fields in the creation and edit forms.