Narrow API scopes with scope modifiers
A scope modifier narrows an API scope to a subset of its operations. To add a modifier, append it to the scope name after a colon, for example clusters:read. A scope without a modifier allows every operation in the scope.
You can use scope modifiers in:
- Scoped personal access tokens
- Scoped OAuth secrets for Databricks service principals
- The
scopeparameter of an OAuth token request, whether you authenticate as a user, authenticate as a service principal, or exchange an identity provider token with workload identity federation
For the full list of scopes and the API operations each one covers, see API scopes.
Available modifiers
:read: Allows only the scope's read operations (GETandHEADrequests). For example,clusters:readallows listing and getting clusters but not creating, editing, or deleting them.:restricted-query: Allows read-only SQL queries. This modifier applies only to thesqlscope. A token withsql:restricted-querycan run queries such asSELECTandDESCRIBEwith the Statement Execution API and SQL drivers and connectors. It can't call other SQL APIs, such as listing SQL warehouses. Statements that modify objects or data fail:- Statements that create, alter, or drop objects, such as
CREATE TABLEandDROP TABLE, fail with[OP_NOT_SUPPORTED_READ_ONLY] ... is not supported in read-only session mode. SQLSTATE: 42KD1. - Statements that modify data, such as
INSERTandUPDATE, fail with[INSUFFICIENT_PERMISSIONS] Insufficient privileges, even on tables you own.
- Statements that create, alter, or drop objects, such as
To combine modifiers, add both: sql:read:restricted-query allows the sql scope's read operations, such as listing SQL warehouses, and read-only queries.
Select an access level in the UI
When you generate a personal access token or an OAuth secret in the workspace UI, after you add a scope, select its access level. The access level sets the modifier:
Access level | Scope granted |
|---|---|
Read |
|
Read + Write |
|
Restricted query ( |
|
Read + Restricted query ( |
|
Read + Restricted query + Write ( |
|
Use modifiers with personal access tokens
With the Token API, include each scope with its modifiers as one item of the scopes array. Personal access tokens don't support all-apis:read. To grant full workspace access, use an empty scopes array (the all-apis scope). See Scoped personal access tokens.
Use modifiers with OAuth
You can bind a Databricks service principal OAuth secret to scopes with modifiers, and you can request an OAuth access token with modifier scopes. An access token can't exceed the scopes of the secret it was minted from, except for a secret with the authentication scope. See Scoped OAuth secrets. OAuth also accepts all-apis:read, which allows read operations on every API the principal is authorized for.
To request a token with modifiers, list the scopes in the scope parameter of the token request, separated by spaces. In the authorization URL of the user-to-machine flow, separate scopes with + instead.