[DOC] custom_app_integration: scopes list is incomplete; link or enumerate full set

[vadivelselvaraj]

Affected Resource(s)

• databricks_custom_app_integration
• Docs page: https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/custom_app_integration

Expected Details

The scopes argument under Argument Reference currently reads:

scopes - OAuth scopes granted to the application. Supported scopes: all-apis, sql, offline_access, openid, profile, email.

This list is not exhaustive. The Databricks REST API surface uses many more API scopes (e.g. unity-catalog, jobs, clusters, apps, dashboards, model-serving, pipelines, mlflow, secrets, vector-search, files, workspace, etc.) that are usable when configuring custom OAuth applications. See API Scopes for the full, authoritative list.

The provider itself does not enforce the documented six values — confirmed by reading the code:

• apps/resource_custom_app_integration.go builds the schema with common.StructToSchema(...) and only attaches validation.IntBetween(...) to the two token_access_policy TTL fields. There is no validation.StringInSlice(...) on scopes, so the field is TypeList of TypeString with no enum.
• The plugin-framework model in internal/service/oauth2_tf/model.go likewise declares Scopes types.List of types.String with no validator; the "Supported scopes: …" comment is auto-generated from the OpenAPI spec.
• Upstream Go SDK (databricks-sdk-go v0.141.0, service/oauth2/model.go) declares Scopes []string on CreateCustomAppIntegration/UpdateCustomAppIntegration/GetCustomAppIntegrationOutput. No Scope enum.
• The provider unit test apps/resource_custom_app_integration_test.go actually uses scopes = ["all"], which is not one of the six values the docs claim are supported, and the test passes. That confirms the docs list is informational only.

So the docs are misleading: users see a closed set of six values, but the provider passes anything through to the API. Please update the docs to either:

1. Link the scopes argument description to the API Scopes reference as the source of truth, or
2. Enumerate all valid scope values inline (sourced from that page) so users don't have to guess which scopes are accepted.

List of things to potentially add/remove

• Update the scopes bullet under "Argument Reference" in docs/resources/custom_app_integration.md to point to https://docs.databricks.com/api/workspace/api/scopes, or
• Replace the short list with the full set of API scope values (access-management, alerts, apps, authentication, cleanrooms, clusters, command-execution, dashboards, dataclassification, dataquality, environments, files, genie, global-init-scripts, identity, instance-pools, instance-profiles, jobs, knowledge-assistants, libraries, marketplace, mlflow, model-serving, networking, notifications, pipelines, postgres, qualitymonitor, query-history, scim, secrets, settings, sharing, sql, supervisor-agents, unity-catalog, vector-search, workspace) plus the OIDC scopes (openid, profile, email, offline_access) and the catch-all all-apis.
• Optionally clarify which scopes are valid only at the account level vs. workspace level, since databricks_custom_app_integration is account-level only.
• Optionally update the upstream OpenAPI spec doc-comment that flows into databricks-sdk-go and internal/service/oauth2_tf/model.go to either drop the stale list or reference the API Scopes page.

Important Factoids

• Resource is account-level only (per the existing note on the docs page).
• The scopes input is forwarded to the Databricks accounts API as-is; the provider performs no client-side enum validation.
• Users hitting this today either trial-and-error scope names, dig through the OpenAPI spec, or inspect the Databricks UI when registering a custom OAuth app.

References

• Terraform docs page: https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/custom_app_integration#argument-reference
• Source file: https://github.com/databricks/terraform-provider-databricks/blob/main/docs/resources/custom_app_integration.md
• Provider resource: https://github.com/databricks/terraform-provider-databricks/blob/main/apps/resource_custom_app_integration.go
• Provider unit test using non-documented scope: https://github.com/databricks/terraform-provider-databricks/blob/main/apps/resource_custom_app_integration_test.go
• Plugin-framework model: https://github.com/databricks/terraform-provider-databricks/blob/main/internal/service/oauth2_tf/model.go
• Upstream Go SDK type: https://github.com/databricks/databricks-sdk-go/blob/v0.141.0/service/oauth2/model.go
• Databricks API Scopes reference: https://docs.databricks.com/api/workspace/api/scopes