Skip to main content

Custom App Integration

View as Markdown

CustomOAuthAppIntegration object​

integration_idstring

ID of this custom app

client_idstring

OAuth client ID that the application uses as client_id in the OAuth flow.

redirect_urlsarray of string

OAuth redirect URLs the application is allowed to use in the authorization flow.

namestring

The display name of the custom OAuth app

confidentialboolean

Whether the application is a confidential client that authenticates with a client secret. Public clients have no client secret.

Default: false

token_access_policyobject

Lifetimes of the access and refresh tokens issued to the application.

Show child attributesHide child attributes
access_token_ttl_in_minutesint32[ 5 .. 1440 ]

Lifetime of access tokens, in minutes.

refresh_token_ttl_in_minutesint32[ 5 .. 129600 ]

Lifetime of refresh tokens, in minutes. Must not be shorter than access_token_ttl_in_minutes. When single-use refresh tokens are enabled, this represents the TTL of an individual refresh token. If the refresh token is used before it expires, a new one is issued with a renewed individual TTL.

enable_single_use_refresh_tokensbooleanBeta

Whether to enable single-use refresh tokens (refresh token rotation). If this feature is enabled, upon successfully getting a new access token using a refresh token, <Databricks> will issue a new refresh token along with the access token in the response and invalidate the old refresh token. The client should use the new refresh token to get access tokens in future requests.

absolute_session_lifetime_in_minutesint32Beta

Absolute OAuth session TTL in minutes. Can only be set when enable_single_use_refresh_tokens is true, and must be at least refresh_token_ttl_in_minutes and at most 525600 (one year). This is the absolute TTL of all refresh tokens issued in one OAuth session. When a new refresh token is issued during refresh token rotation, it will inherit the same absolute TTL as the old refresh token. In other words, this represents the maximum amount of time a user can stay logged in without re-authenticating.

scopesarray of string

OAuth scopes the application is allowed to request.

created_byint64

ID of the user who created the integration.

create_timestring

Time the integration was created, as an ISO 8601 timestamp.

creator_usernamestring

Username of the user who created the integration. Only returned by the list method when include_creator_username is true.

user_authorized_scopesarray of string

Scopes that will need to be consented by end user to mint the access token. If the user does not authorize the access token will not be minted. Must be a subset of scopes.

Get OAuth Custom App Integration GA​

GET /api/2.0/accounts/{account_id}/oauth2/custom-app-integrations/{integration_id}

Gets the Custom OAuth App Integration for the given integration id.

API scopes: authentication

Parameters​

account_idstringRequiredpath

The account ID.

integration_idstringRequiredpath

The OAuth app integration ID.

Response​

Returns the CustomOAuthAppIntegration object.

Get custom oauth app integrations GA​

GET /api/2.0/accounts/{account_id}/oauth2/custom-app-integrations

Get the list of custom OAuth app integrations for the specified <Databricks> account.

API scopes: authentication

Parameters​

account_idstringRequiredpath
page_tokenstringquery

Token from the next_page_token field of a previous response. Omit it to request the first page.

page_sizeint32query

Maximum number of integrations to return in one page, at most 1000.

Default: 100

include_creator_usernamebooleanquery

When true, each returned integration includes creator_username.

Response​

Returns a list of CustomOAuthAppIntegration objects.

Create Custom OAuth App Integration GA​

POST /api/2.0/accounts/{account_id}/oauth2/custom-app-integrations

Create Custom OAuth App Integration.

You can retrieve the custom OAuth app integration via CustomAppIntegration/get.

API scopes: authentication

Parameters​

account_idstringRequiredpath

Request body​

redirect_urlsarray of string

OAuth redirect URLs for the application. Each URL must use https, except loopback URLs (localhost, 127.0.0.1 or ::1), which may use http. At most 100 URLs of at most 256 characters each.

namestring

Name of the custom OAuth app

confidentialboolean

Whether to create a confidential client that authenticates with a client secret. Public clients receive no client secret.

Default: false

token_access_policyobject

Lifetimes of the tokens issued to the application. If omitted, access tokens are valid for 60 minutes and refresh tokens for 7 days (10080 minutes). If set, both TTL fields are required.

Show child attributesHide child attributes
access_token_ttl_in_minutesint32[ 5 .. 1440 ]

Lifetime of access tokens, in minutes.

refresh_token_ttl_in_minutesint32[ 5 .. 129600 ]

Lifetime of refresh tokens, in minutes. Must not be shorter than access_token_ttl_in_minutes. When single-use refresh tokens are enabled, this represents the TTL of an individual refresh token. If the refresh token is used before it expires, a new one is issued with a renewed individual TTL.

enable_single_use_refresh_tokensbooleanBeta

Whether to enable single-use refresh tokens (refresh token rotation). If this feature is enabled, upon successfully getting a new access token using a refresh token, <Databricks> will issue a new refresh token along with the access token in the response and invalidate the old refresh token. The client should use the new refresh token to get access tokens in future requests.

absolute_session_lifetime_in_minutesint32Beta

Absolute OAuth session TTL in minutes. Can only be set when enable_single_use_refresh_tokens is true, and must be at least refresh_token_ttl_in_minutes and at most 525600 (one year). This is the absolute TTL of all refresh tokens issued in one OAuth session. When a new refresh token is issued during refresh token rotation, it will inherit the same absolute TTL as the old refresh token. In other words, this represents the maximum amount of time a user can stay logged in without re-authenticating.

scopesarray of string

OAuth scopes granted to the application. At least one scope is required. Supported scopes: all-apis, sql, offline_access, openid, profile, email, and the fine-grained API scopes listed at https://docs.databricks.com/api/account/scopes.

user_authorized_scopesarray of string

Scopes that will need to be consented by end user to mint the access token. If the user does not authorize the access token will not be minted. Must be a subset of scopes.

Response​

integration_idstring

Unique integration id for the custom OAuth app

client_idstring

OAuth client ID generated by <Databricks>.

client_secretstring

OAuth client secret generated by <Databricks> for confidential apps; empty for public apps. It is only returned in this response and cannot be retrieved later, so store it securely.

Updates Custom OAuth App Integration GA​

PATCH /api/2.0/accounts/{account_id}/oauth2/custom-app-integrations/{integration_id}

Updates an existing custom OAuth App Integration. You can retrieve the custom OAuth app integration via CustomAppIntegration/get.

API scopes: authentication

Parameters​

account_idstringRequiredpath
integration_idstringRequiredpath

ID of the custom OAuth app integration to update.

Request body​

redirect_urlsarray of string

New OAuth redirect URLs for the application. Replaces the existing list; same constraints as on create.

token_access_policyobject

New token lifetimes for the application. Both TTL fields are required when the policy is set; the single-use refresh token settings keep their current values when omitted.

Show child attributesHide child attributes
access_token_ttl_in_minutesint32[ 5 .. 1440 ]

Lifetime of access tokens, in minutes.

refresh_token_ttl_in_minutesint32[ 5 .. 129600 ]

Lifetime of refresh tokens, in minutes. Must not be shorter than access_token_ttl_in_minutes. When single-use refresh tokens are enabled, this represents the TTL of an individual refresh token. If the refresh token is used before it expires, a new one is issued with a renewed individual TTL.

enable_single_use_refresh_tokensbooleanBeta

Whether to enable single-use refresh tokens (refresh token rotation). If this feature is enabled, upon successfully getting a new access token using a refresh token, <Databricks> will issue a new refresh token along with the access token in the response and invalidate the old refresh token. The client should use the new refresh token to get access tokens in future requests.

absolute_session_lifetime_in_minutesint32Beta

Absolute OAuth session TTL in minutes. Can only be set when enable_single_use_refresh_tokens is true, and must be at least refresh_token_ttl_in_minutes and at most 525600 (one year). This is the absolute TTL of all refresh tokens issued in one OAuth session. When a new refresh token is issued during refresh token rotation, it will inherit the same absolute TTL as the old refresh token. In other words, this represents the maximum amount of time a user can stay logged in without re-authenticating.

scopesarray of string

List of OAuth scopes to be updated in the custom OAuth app integration, similar to redirect URIs this will fully replace the existing values instead of appending

user_authorized_scopesarray of string

Scopes that will need to be consented by end user to mint the access token. If the user does not authorize the access token will not be minted. Must be a subset of scopes.

Delete Custom OAuth App Integration GA​

DELETE /api/2.0/accounts/{account_id}/oauth2/custom-app-integrations/{integration_id}

Delete an existing Custom OAuth App Integration. You can retrieve the custom OAuth app integration via CustomAppIntegration/get.

API scopes: authentication

Parameters​

account_idstringRequiredpath
integration_idstringRequiredpath

ID of the custom OAuth app integration to delete.