Scopes in your tenant
Define the access names applications can request from your tenant and decide which clients may use them.
For the concepts behind these controls, learn about grants, scopes, and consent.
This guide describes tenant configuration and discovery. Client credentials and authorization codes can issue access tokens when enabled. Creating a scope does not implement an API permission or issue a token by itself.
The same scope rules apply to BTL's own organization. BTL administrators can open BTL Admin, OAuth Management, Scopes and Clients. BTL's OAuth Audit and Logs are in that same sidebar group.
Common and exclusive
Every scope belongs to one tenant. Its access setting determines both client eligibility and discovery visibility. There is no separate discovery switch.
| Access | Eligible clients | Discovery |
|---|---|---|
| Common | Clients with restrictScopes turned off, without explicit assignment. | Included in scopes_supported. |
| Exclusive | Only explicitly assigned clients, whether restricted or unrestricted. | Omitted from scopes_supported. |
Exclusive does not mean one client only. You can assign the same exclusive scope to several clients. Scope names and configuration in another tenant do not change this tenant's policy.
Create a scope
- Open OAuth Management, Scopes and select the intended tenant.
- Select Create scope. Enter a name, such as
orders:read, and a description explaining its purpose. - Choose Exclusive, the default, or Common, then save.
Names are case-sensitive and remain fixed after creation. Use up to 100 visible ASCII characters, excluding spaces, quotation marks, and backslashes. Descriptions allow up to 500 characters. The same name cannot be reused for another active scope in that tenant.
Client scope access
In Clients, edit a client and enter existing scope names under Assigned scopes, one per line. Exclusive scopes always require an explicit assignment.
Restrict scopes stores restrictScopes. When turned on, it blocks every common scope, including one that was explicitly assigned. A restricted client can use only its assigned exclusive scopes. Saving a restricted client with a common scope assignment is rejected.
When turned off, the client can use common scopes plus its assigned exclusive scopes. This does not bypass the client's enabled status or any other authorization rule.
For example, define catalog:read as common and orders:write as exclusive. An unrestricted client is eligible for catalog:read. It needs an assignment for orders:write. A restricted client assigned orders:write is eligible only for that scope and cannot use catalog:read.
Discovery
On the tenant's own hostname, fetch either discovery document: /.well-known/openid-configuration or /.well-known/oauth-authorization-server. A common scope appears in the scopes_supported array; an exclusive scope does not.
{ "scopes_supported": ["catalog:read"] }This is an illustrative excerpt for the example above, not a complete response. Discovery is public information about the tenant. Being listed does not grant access to a resource, and being omitted does not make a scope name a secret.
Edit or delete
You can edit a scope's description and access setting. To rename a scope, remove its client assignments, delete it, and create the new name. Before changing an exclusive scope to common, remove it from every restricted client; otherwise the change is rejected.
Deletion is blocked while explicit client assignments remain. Remove those assignments in Clients first. Scope edits and deletion revoke stored grants and affected remembered consents; client edits revoke that client's grants, pending codes, and remembered consents. Previously issued access tokens are revoked by the client change.
If another administrator changes the record while you are editing it, reload the current version and reapply your intended change. If saving fails, read the error before proceeding; an unavailable service or missing permission must not be treated as a successful save.
Permissions and history
Reading, creating, updating, and deleting scopes each require a separate tenant permission. Client assignments require client update permission. The service checks current authorization for the selected tenant on every operation. Choosing a tenant in the selector does not grant access.
In the tenant's Audit or Logs view, choose OAuth management to inspect recorded operations and outcomes. Each history view requires its own read permission. Deleting configuration leaves retained history intact.
Shared service limits allow 100 active scopes and 200 active clients per tenant, with up to 50 assigned scopes per client. These capacity limits protect the shared service.