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. While any Route, MCP Server, or AI Agent references the scope, the server refuses to rename or delete it — check the Authorized resources section (the Routes, MCP Servers, and AI Agents tabs) on the Scope details screen before trying.

Quick links

Learn how to:

• List Scopes
• Create a Scope
• View Scope relationships
• Edit a Scope
• Delete a Scope
• Review the Audit Log record
• Review the form fields
• Check the permissions

Listing

The Scopes page lists registered scopes with pagination. The Create Scope button, above the table, opens the registration form.

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, each shown based on the user's permission — see Permissions. The whole column disappears when neither icon is available.

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). It opens the read-only Scope details screen (route /scopes/<scopeId>/overview) with:

• Name and Description for the scope.
• Authorized resources section, with the Routes, MCP Servers, and AI Agents tabs, each showing the total number of relationships of that type next to the tab name, and listing every resource that references this scope with Display name, Owner ID, and Authorization Policy Target ID columns.
• Edit button in the Scope information card header, above the Name and Description fields, 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

Editing happens inside the details screen. Open the scope's Overview (see View Scope) and, on Scope details, click the Edit button in the Scope information card header. The Update Scope form opens over the details screen, at route /scopes/<scopeId>/overview/edit, with the current data, and shows, below the editable fields and with no section heading, the same Routes, MCP Servers, and AI Agents tabs described in View Scope.

A SCOPE IN USE CANNOT BE RENAMED

When the scope is already in use — referenced by at least one Route, MCP Server, or AI Agent — the server refuses the Name change. Check the Routes, MCP Servers, and AI Agents tabs to see whether the scope is in use before trying to rename it.

Change the required fields and click Save. Saving or canceling closes the form and returns to the Scope details screen for the same scope.

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.

Audit Log record

Creating, editing, or deleting a scope generates a queryable record in the Access Control Audit Log, with the date, the author, the outcome of the operation, and the content of the object. Listing a scope, opening its details, or viewing its relationships does not generate a record: only write operations are audited.

The record can be queried by filtering on Scope, a value exclusive to AI Gateway, so you do not need to combine it with the Product filter. In the Name column of the Audit Logs screen you see the scope identifier, not its name, except on a failed creation: the identifier only exists once the creation succeeds, so the field stays empty. On an update or a deletion, the identifier appears as it was sent in the request, even when it is malformed.

On success, the record content is the scope identifier, name, and description: the state after the operation for a creation and an update, and the state read before removal for a deletion. The Authorized resources data and dates are not part of the content.

A request refused right at the entry point (for example, a Name that is blank, contains a space, or exceeds 255 characters, or a Description above 1024 characters) generates no record. From the moment the operation is processed, both success and failure generate a record, with the refusal reason and the content that was attempted: a name already used by another scope, a scope that does not exist, a malformed id, and the refusal to rename or delete a scope in use all show up in the trail as a failure. When the failure is unexpected, the reason is a generic message.

On a failed creation, the content shows the name and description as they were sent; on an update, it also shows the id provided; on a failed deletion, it is the state of the scope read before removal. When the scope cannot be read before removal (malformed id, nonexistent scope, or a read that failed), the deletion record carries only the identifier.

"In use", for the refusal, means referenced by a Route, an MCP Server, or an AI Agent. The tabs in the Authorized resources section show those resources. The reason stored in the failure lists the resources related to the scope. If the gateway cannot verify usage, the name change or the deletion is refused and the failure record carries that reason.

Querying the Audit Log uses the Audit List and Audit View permissions, which already govern that screen.

Form fields

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

Permissions

Access to each action in the Scopes journey depends on its own permission. Without the corresponding permission, the screen element does not appear — the interface never shows an unavailable action as disabled.

Permissions are granted in Access Control, on the Roles screen, under the AI Gateway product. The table below lists each one exactly as Access Control displays it.

A control without its permission is not rendered; a route reached directly by URL without its permission lands on the AI Gateway's own access denied screen, not on Access Control's.

EDITING REQUIRES VIEWING

The Edit button only exists inside the Scope details screen. Because of that, a user holding Create and Update Scopes but not View Scope has no path to edit an existing scope. This is expected platform behavior, not a bug.