Add a secret resource to a Databricks app

Add Databricks secrets as Databricks Apps resources to securely pass sensitive values, such as API keys or tokens, to your app. Databricks Apps supports secrets stored in secret scopes. Apps retrieve these secrets at runtime, which keeps them out of your application code and environment definitions.

Add a secret resource

Before you can add a secret as an app resource, check that you meet the prerequisites.

Follow the steps in this guide to add a resource. Select Secret as the resource type. Then:

1. Choose a secret scope.
2. Select a secret key within that scope to use in your app.
3. Choose a permission level for the scope (not the individual secret):
   • Can read: Grants the app read access to all secrets in the selected scope.
   • Can write: Grants the app permission to update any secret in the scope.
   • Can manage: Grants the app permission to read, update, and delete any secret in the scope.
4. (Optional) Specify a custom resource key, which is how you reference the secret in your app configuration. The default key is secret.

note

These steps allow the app to securely access a selected secret from the scope by passing its value as an environment variable.

Secret permissions apply at the scope level, however, not the individual secret. To limit access between apps, create a separate secret scope for each app and store only the required secrets in that scope.

Environment variables

When you deploy an app that uses secret resources, Databricks injects each secret as an environment variable. The name of each variable matches the resource key that you defined when you added the secret.

To access the secret from your app, use that environment variable. In your app configuration file (such as app.yaml), define a variable that references the secret using the valueFrom field. This setup ensures the actual secret value remains securely managed by Databricks and is not exposed in plaintext.

If you use the same secret across multiple resource entries with different resource keys, each one becomes a separate environment variable when referenced in valueFrom.

For more information, see Access environment variables from resources.

important

Never store sensitive values directly in environment variables or your app code. Instead, pass the resource key to Databricks as an environment variable, and retrieve the secret value securely at runtime.

Remove a secret resource

When you remove a secret resource from an app, the secret itself remains in the secret scope. However, the app loses access to the secret unless you add it again.

Best practices

Follow these best practices when managing secrets in your app:

• Don’t expose raw secret values. Secret values injected directly as environment variables appear in plaintext on the app's Environment page. To avoid this, reference the secret using the valueFrom field in your app configuration and retrieve the value securely within your app code.
• Limit the app's access to only the specific scopes it needs. Avoid granting access to all scopes in the workspace.
• Establish a rotation schedule for all secrets, and rotate immediately when a team member changes roles or leaves your organization.