Secrets API
The Secrets API allows you to manage secrets, secret scopes, and access permissions. To manage secrets, you must:
- Create a secret scope.
- Add your secrets to the scope.
- If you have the Databricks Operational Security Package, assign access control to the secret scope.
To learn more about creating and managing secrets, see Secrets. You access and reference secrets in notebooks and jobs by using Secrets utilities.
Table of Contents
Create Secret Scope
Endpoint | HTTP Method |
---|---|
2.0/secrets/scopes/create |
POST |
Creates a new secret scope.
The scope name must consist of alphanumeric characters, dashes, underscores, and periods, and may not exceed 128 characters. The maximum number of scopes in a workspace is 100.
Example request:
{
"scope": "my-simple-databricks-scope",
"initial_manage_principal": "users"
}
If initial_manage_principal
is specified, the initial ACL applied to the scope is
applied to the supplied principal (user or group) with MANAGE
permissions.
The only supported principal for this option is the group users
, which
contains all users in the workspace. If initial_manage_principal
is not specified,
the initial ACL with MANAGE
permission applied to the scope is assigned to the
API request issuer’s user identity.
Throws RESOURCE_ALREADY_EXISTS
if a scope with the given name already exists.
Throws RESOURCE_LIMIT_EXCEEDED
if maximum number of scopes in the workspace is exceeded.
Throws INVALID_PARAMETER_VALUE
if the scope name is invalid.
Delete Secret Scope
Endpoint | HTTP Method |
---|---|
2.0/secrets/scopes/delete |
POST |
Deletes a secret scope.
Example request:
{
"scope": "my-secret-scope"
}
Throws RESOURCE_DOES_NOT_EXIST
if the scope does not exist.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
List Secret Scopes
Endpoint | HTTP Method |
---|---|
2.0/secrets/scopes/list |
GET |
Lists all secret scopes available in the workspace.
Example response:
{
"scopes": [{
"name": "my-databricks-scope",
"backend_type": "DATABRICKS"
},{
"name": "mount-points",
"backend_type": "DATABRICKS"
}]
}
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Response Structure
Field Name | Type | Description |
---|---|---|
scopes | An array of SecretScope | The available secret scopes. |
Put Secret
Endpoint | HTTP Method |
---|---|
2.0/secrets/put |
POST |
Inserts a secret under the provided scope with the given name. If a secret already
exists with the same name, this command overwrites the existing secret’s value.
The server encrypts the secret using the secret scope’s encryption settings before
storing it. You must have WRITE
or MANAGE
permission on the secret scope.
The secret key must consist of alphanumeric characters, dashes, underscores, and periods, and cannot exceed 128 characters. The maximum allowed secret value size is 128 KB. The maximum number of secrets in a given scope is 1000.
Example request:
{
"scope": "my-databricks-scope",
"key": "my-string-key",
"string_value": "foobar"
}
The input fields “string_value” or “bytes_value” specify the type of the secret, which will determine the value returned when the secret value is requested. Exactly one must be specified.
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope exists.
Throws RESOURCE_LIMIT_EXCEEDED
if maximum number of secrets in scope is exceeded.
Throws INVALID_PARAMETER_VALUE
if the key name or value length is invalid.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Request Structure
Field Name | Type | Description |
---|---|---|
string_value OR bytes_value |
STRING OR BYTES |
If If |
scope | STRING |
The name of the scope to which the secret will be associated with. This field is required. |
key | STRING |
A unique name to identify the secret. This field is required. |
Delete Secret
Endpoint | HTTP Method |
---|---|
2.0/secrets/delete |
POST |
Deletes the secret stored in this secret scope. You must have WRITE
or MANAGE
permission on the secret scope.
Example request:
{
"scope": "my-secret-scope",
"key": "my-secret-key"
}
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope or secret exists.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
List Secrets
Endpoint | HTTP Method |
---|---|
2.0/secrets/list |
GET |
Lists the secret keys that are stored at this scope. This is a metadata-only
operation; secret data cannot be retrieved using this API. Users need READ
permission to make this call.
Example response:
{
"secrets": [
{
"key": "my-string-key",
"last_updated_timestamp": "1520467595000"
},
{
"key": "my-byte-key",
"last_updated_timestamp": "1520467595000"
},
]
}
The lastUpdatedTimestamp returned is in milliseconds since epoch.
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope exists.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Request Structure
Field Name | Type | Description |
---|---|---|
scope | STRING |
The name of the scope whose secrets you want to list. This field is required. |
Response Structure
Field Name | Type | Description |
---|---|---|
secrets | An array of SecretMetadata | Metadata information of all secrets contained within the given scope. |
Put Secret ACL
Endpoint | HTTP Method |
---|---|
2.0/secrets/acls/put |
POST |
Creates or overwrites the ACL associated with the given principal (user or group) on the specified scope point. In general, a user or group will use the most powerful permission available to them, and permissions are ordered as follows:
MANAGE
- Allowed to change ACLs, and read and write to this secret scope.WRITE
- Allowed to read and write to this secret scope.READ
- Allowed to read this secret scope and list what secrets are available.
Note that in general, secret values can only be read from within a command
on a cluster (for example, through a notebook). There is no API to read the actual
secret value material outside of a cluster. However, the user’s permission will be
applied based on who is executing the command, and they must have at least READ
permission.
Users must have the MANAGE
permission to invoke this API.
Example request:
{
"scope": "my-secret-scope",
"principal": "data-scientists",
"permission": "READ"
}
The principal is a user or group name corresponding to an existing Databricks principal to be granted or revoked access.
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope exists.
Throws RESOURCE_ALREADY_EXISTS
if a permission for the principal already exists.
Throws INVALID_PARAMETER_VALUE
if the permission is invalid.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Request Structure
Field Name | Type | Description |
---|---|---|
scope | STRING |
The name of the scope to apply permissions to. This field is required. |
principal | STRING |
The principal to which the permission is applied. This field is required. |
permission | AclPermission | The permission level applied to the principal. This field is required. |
Delete Secret ACL
Endpoint | HTTP Method |
---|---|
2.0/secrets/acls/delete |
POST |
Deletes the given ACL on the given scope.
Users must have the MANAGE
permission to invoke this API.
Example request:
{
"scope": "my-secret-scope",
"principal": "data-scientists"
}
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope, principal, or ACL exists.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Get Secret ACL
Endpoint | HTTP Method |
---|---|
2.0/secrets/acls/get |
GET |
Describes the details about the given ACL, such as the group and permission.
Users must have the MANAGE
permission to invoke this API.
Example response:
{
"principal": "data-scientists",
"permission": "READ"
}
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope exists.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Request Structure
Field Name | Type | Description |
---|---|---|
scope | STRING |
The name of the scope to fetch ACL information from. This field is required. |
principal | STRING |
The principal to fetch ACL information for. This field is required. |
Response Structure
Field Name | Type | Description |
---|---|---|
principal | STRING |
The principal to which the permission is applied. This field is required. |
permission | AclPermission | The permission level applied to the principal. This field is required. |
List Secret ACLs
Endpoint | HTTP Method |
---|---|
2.0/secrets/acls/list |
GET |
Lists the ACLs set on the given scope.
Users must have the MANAGE
permission to invoke this API.
Example response:
{
"acls": [
{
"principal": "admins",
"permission": "MANAGE"
},{
"principal": "data-scientists",
"permission": "READ"
}
]
}
Throws RESOURCE_DOES_NOT_EXIST
if no such secret scope exists.
Throws PERMISSION_DENIED
if the user does not have permission to make this API call.
Request Structure
Field Name | Type | Description |
---|---|---|
scope | STRING |
The name of the scope to fetch ACL information from. This field is required. |
Response Structure
Field Name | Type | Description |
---|---|---|
items | An array of AclItem | The associated ACLs rule applied to principals in the given scope. |
Data Structures
AclItem
An item representing an ACL rule applied to the given principal (user or group) on the associated scope point.
Field Name | Type | Description |
---|---|---|
principal | STRING |
The principal to which the permission is applied. This field is required. |
permission | AclPermission | The permission level applied to the principal. This field is required. |
SecretMetadata
The metadata about a secret. Returned when listing secrets. Does not contain the actual secret value.
Field Name | Type | Description |
---|---|---|
key | STRING |
A unique name to identify the secret. |
last_updated_timestamp | INT64 |
The last updated timestamp (in milliseconds) for the secret. |
SecretScope
An organizational resource for storing secrets. Secret scopes can be different types, and ACLs can be applied to control permissions for all secrets within a scope.
Field Name | Type | Description |
---|---|---|
name | STRING |
A unique name to identify the secret scope. |
backend_type | ScopeBackendType | The type of secret scope backend. |
AclPermission
The ACL permission levels for secret ACLs applied to secret scopes.
Permission | Description |
---|---|
READ | Allowed to perform read operations (get, list) on secrets in this scope. |
WRITE | Allowed to read and write secrets to this secret scope. |
MANAGE | Allowed to read/write ACLs, and read/write secrets to this secret scope. |
ScopeBackendType
The type of secret scope backend.
Only a Databricks-backed secret scope is supported.
Type | Description |
---|---|
DATABRICKS | A secret scope in which secrets are stored in Databricks managed storage and encrypted with a cloud-based specific encryption key. |