OAuth reference

This page provides reference documentation for OAuth integration with Databricks, including endpoints, driver version requirements, and sample code.

Workspace-level OAuth endpoints

Description	Endpoint URL
OAuth well-known configuration	`https://{databricks-host}/oidc/.well-known/openid-configuration`
OAuth token endpoint	`https://{databricks-host}/oidc/v1/token`
OAuth authorization endpoint	`https://{databricks-host}/oidc/v1/authorize`

Description	Endpoint URL
AWS well-known configuration	`https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/.well-known/openid-configuration`
Azure well-known configuration	`https://accounts.azuredatabricks.net/oidc/accounts/<account-id>/.well-known/openid-configuration`
GCP well-known configuration	`https://accounts.gcp.databricks.com/oidc/accounts/<account-id>/.well-known/openid-configuration`
OAuth authorization endpoint	`https://<cloud-specific-url>/oidc/accounts/<account-id>/v1/authorize`
OAuth token endpoint	`https://<cloud-specific-url>/oidc/accounts/<account-id>/v1/token`

M2M flows:

See secrets lifetime and access token lifetime in Authorizing service principal access with OAuth

U2M flows:

See access token TTL and refresh token TTL in Enabling partner OAuth applications
See OAuth session TTL options in Single-use refresh tokens

OAuth refresh tokens are long-lived. Persist refresh tokens to avoid requiring users to re-authenticate:

Store tokens per user session on the application backend
Scope token storage to (workspace-host, user) tuples for multi-tenant applications
Implement secure storage using encryption at rest
Handle token expiration gracefully with automatic refresh

Always use PKCE (Proof Key for Code Exchange) for U2M flows:

Generate a cryptographically random code_verifier (43-128 characters)
Create code_challenge as Base64URL(SHA256(code_verifier))
Include code_challenge and code_challenge_method=S256 in authorization request
Include code_verifier in token exchange request

Handle common OAuth errors:

Error	Cause	Resolution
`invalid_grant`	Expired or revoked refresh token	Re-initiate OAuth flow
`invalid_client`	Incorrect client credentials	Verify client ID and secret
`access_denied`	User denied authorization	Prompt user to retry
`invalid_scope`	Requested scope not allowed	Check registered scopes