Workspace User

View as Markdown

A user in your Databricks account.

Get a user in the accountGET /api/2.0/identity/{name=users/*}List users in the accountGET /api/2.0/identity/usersCreate a user in the accountPOST /api/2.0/identity/usersUpdate a user in the accountPATCH /api/2.0/identity/{name=users/*}Delete a user in the accountDELETE /api/2.0/identity/{name=users/*}Resolve an external user in the Databricks accountPOST /api/2.0/identity/users/resolve-by-external-id

User object

A user in your Databricks account.

namestringIDImmutable

The resource name of the user, in one of these formats:

• Account APIs: accounts/{account_id}/users/{user_id}
• Workspace APIs: users/{user_id}

parentstringOutput onlyImmutable

The resource name of the account that contains the user, in the format accounts/{account_id}. Workspace APIs return the same format.

account_idstringOutput onlyImmutable

The ID of the account that contains the user.

user_idstringOutput onlyImmutable

The Databricks ID of the user.

external_idstring

The ID of the user in your identity provider (IdP).

usernamestringImmutable

The user's username, which is their email address. It can't be changed after the user is created.

full_nameobject

The user's name.

Show child attributesHide child attributes

given_namestring

The user's given (first) name.

family_namestring

The user's family (last) name.

account_user_statusstring

Whether the user is active in the account. New users are active unless you set this to INACTIVE.

Values:

• ACTIVE
• INACTIVE

View as Markdown

The User object

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "user_id": "string",
  "external_id": "string",
  "username": "string",
  "full_name": {
    "given_name": "string",
    "family_name": "string"
  },
  "account_user_status": "ACTIVE"
}

Get a user in the account GA

GET /api/2.0/identity/{name=users/*}

Gets a user in the account that contains this workspace by their Databricks ID.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the user, in the format users/{user_id}.

Response

Returns the User object.

View as Markdown

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "user_id": "string",
  "external_id": "string",
  "username": "string",
  "full_name": {
    "given_name": "string",
    "family_name": "string"
  },
  "account_user_status": "ACTIVE"
}

List users in the account GA

GET /api/2.0/identity/users

Lists the users in the account that contains this workspace, sorted by Databricks ID. Users in your identity provider who haven't been added to Databricks aren't included.

API scopes: identity

Parameters

page_sizeint32query

The maximum number of users to return, up to 1000. The default is 1000. A page can contain fewer users.

page_tokenstringquery

The next_page_token from a previous response, to get the next page.

filterstringquery

Filters users by username or external_id, for example username eq "someone@example.com". Put the value in quotes.

parentstringquery

The resource name of the account to list users in, in the format accounts/{account_id}. Defaults to the account that contains this workspace. Any other account is rejected.

Response

Returns a list of User objects.

View as Markdown

Response

{
  "users": [
    {
      "name": "string",
      "parent": "string",
      "account_id": "string",
      "user_id": "string",
      "external_id": "string",
      "username": "string",
      "full_name": {},
      "account_user_status": "ACTIVE"
    }
  ],
  "next_page_token": "string"
}

Create a user in the account GA

POST /api/2.0/identity/users

Creates a local user in the account that contains this workspace. A local user is a user that isn't synced from your identity provider (IdP).

If automatic identity management is on, you can't set external_id. To add a user from your IdP, get them as an external user instead.

API scopes: identity

Parameters

parentstringquery

The resource name of the account to create the user in, in the format accounts/{account_id}. Defaults to the account that contains this workspace. Any other account is rejected.

Request body

The user to create.

namestringIDImmutable

The resource name of the user, in one of these formats:

• Account APIs: accounts/{account_id}/users/{user_id}
• Workspace APIs: users/{user_id}

external_idstring

The ID of the user in your identity provider (IdP).

usernamestringRequiredImmutable

The user's username, which is their email address. It can't be changed after the user is created.

full_nameobjectRequired

The user's name.

Show child attributesHide child attributes

given_namestring

The user's given (first) name.

family_namestring

The user's family (last) name.

account_user_statusstringRequired

Whether the user is active in the account. New users are active unless you set this to INACTIVE.

Values:

• ACTIVE
• INACTIVE

Response

Returns the User object.

View as Markdown

Request

{
  "name": "string",
  "external_id": "string",
  "username": "string",
  "full_name": {
    "given_name": "string",
    "family_name": "string"
  },
  "account_user_status": "ACTIVE"
}

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "user_id": "string",
  "external_id": "string",
  "username": "string",
  "full_name": {
    "given_name": "string",
    "family_name": "string"
  },
  "account_user_status": "ACTIVE"
}

Update a user in the account GA

PATCH /api/2.0/identity/{name=users/*}

Updates a user in the account that contains this workspace. Only the fields in update_mask change.

If automatic identity management is on and the user has an external_id, you can only update external_id. The user's other fields come from your identity provider. You can't deactivate yourself or change the status of the account owner.

API scopes: identity

Parameters

namestringRequiredIDImmutablepath

The resource name of the user, in one of these formats:

• Account APIs: accounts/{account_id}/users/{user_id}
• Workspace APIs: users/{user_id}

update_maskstringRequiredquery

The fields to update, separated by commas. You can update full_name.given_name, full_name.family_name, account_user_status, and external_id.

Request body

The user to update. Its name identifies the user.

external_idstring

The ID of the user in your identity provider (IdP).

usernamestringRequiredImmutable

The user's username, which is their email address. It can't be changed after the user is created.

full_nameobjectRequired

The user's name.

Show child attributesHide child attributes

given_namestring

The user's given (first) name.

family_namestring

The user's family (last) name.

account_user_statusstringRequired

Whether the user is active in the account. New users are active unless you set this to INACTIVE.

Values:

• ACTIVE
• INACTIVE

Response

Returns the User object.

View as Markdown

Request

{
  "external_id": "string",
  "username": "string",
  "full_name": {
    "given_name": "string",
    "family_name": "string"
  },
  "account_user_status": "ACTIVE"
}

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "user_id": "string",
  "external_id": "string",
  "username": "string",
  "full_name": {
    "given_name": "string",
    "family_name": "string"
  },
  "account_user_status": "ACTIVE"
}

Delete a user in the account GA

DELETE /api/2.0/identity/{name=users/*}

Deletes a user from the account that contains this workspace and removes them from the workspaces they're assigned to.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the user, in the format users/{user_id}.

View as Markdown

Response

{}

Resolve an external user in the Databricks account Beta

POST /api/2.0/identity/users/resolve-by-external-id

Gets a user by their ID in your identity provider (IdP) and syncs their details and group memberships from your IdP. If the user isn't in the account that contains this workspace yet, they're added. Requires automatic identity management.

API scopes: identity

Request body

external_idstringRequired

The ID of the user in your IdP.

Response

userobject

The resolved user.

Show child attributesHide child attributes

namestringIDImmutable

The resource name of the user, in one of these formats:

• Account APIs: accounts/{account_id}/users/{user_id}
• Workspace APIs: users/{user_id}

parentstringOutput onlyImmutable

The resource name of the account that contains the user, in the format accounts/{account_id}. Workspace APIs return the same format.

account_idstringOutput onlyImmutable

The ID of the account that contains the user.

user_idstringOutput onlyImmutable

The Databricks ID of the user.

external_idstring

The ID of the user in your identity provider (IdP).

usernamestringRequiredImmutable

The user's username, which is their email address. It can't be changed after the user is created.

full_nameobjectRequired

The user's name.

Show child attributesHide child attributes

given_namestring

The user's given (first) name.

family_namestring

The user's family (last) name.

account_user_statusstringRequired

Whether the user is active in the account. New users are active unless you set this to INACTIVE.

Values:

• ACTIVE
• INACTIVE

View as Markdown

Request

{
  "external_id": "string"
}

Response

{
  "user": {
    "name": "string",
    "parent": "string",
    "account_id": "string",
    "user_id": "string",
    "external_id": "string",
    "username": "string",
    "full_name": {},
    "account_user_status": "ACTIVE"
  }
}