Skip to main content

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:

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 (GET and HEAD requests). For example, clusters:read allows listing and getting clusters but not creating, editing, or deleting them.
  • :restricted-query: Allows read-only SQL queries. This modifier applies only to the sql scope. A token with sql:restricted-query can run queries such as SELECT and DESCRIBE with 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 TABLE and DROP TABLE, fail with [OP_NOT_SUPPORTED_READ_ONLY] ... is not supported in read-only session mode. SQLSTATE: 42KD1.
    • Statements that modify data, such as INSERT and UPDATE, fail with [INSUFFICIENT_PERMISSIONS] Insufficient privileges, even on tables you own.

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

<scope>:read

Read + Write

<scope> (no modifier)

Restricted query (sql only)

sql:restricted-query

Read + Restricted query (sql only)

sql:read:restricted-query

Read + Restricted query + Write (sql only)

sql (no modifier)

Access level

Scope granted

Read

<scope>:read

Read + Write

<scope> (no modifier)

Restricted query (sql only)

sql:restricted-query

Read + Restricted query (sql only)

sql:read:restricted-query

Read + Restricted query + Write (sql only)

sql (no modifier)

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.

Additional resources​