Skip to main content
Version: current [24.3.x]

User Enterprise

Use the User API to manage Dremio users, their privileges, and their personal access tokens.

User Object
{
"@type": "EnterpriseUser",
"id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
"name": "dremio",
"firstName": "Dre",
"lastName": "Mio",
"email": "user@dremio.com",
"tag": "EuCNt1nnvdI=",
"roles": [
{
"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
"name": "PUBLIC",
"type": "SYSTEM"
},
{
"id": "43dce6d7-40ff-4afa-9901-71c30eb92744",
"name": "ADMIN",
"type": "SYSTEM"
}
],
"source": "local",
"active": true
}

User Attributes

@type String

Type of user.

Enum: EnterpriseUser, User

Example: EnterpriseUser


id String (UUID)

Unique identifier of the user.

Example: b9dbebc7-bc3b-4d56-9154-31762ab65a43


name String

Username of the Dremio user account.

Example: dremio


firstName String

User's first name.

Example: Dre


lastName String

User's last name.

Example: Mio


email String

User's email address. If the user is managed with the Dremio Okta application, email is the primary email address in the user's Okta profile. If the user is managed with Microsoft Azure Active Directory (AD), email is the work email address in the user's Azure AD profile.

Example: user@dremio.com


tag String

Unique identifier of the user version. Dremio changes the tag whenever the user changes and uses the tag to ensure that PUT requests apply to the most recent version of the user.

Example: EuCNt1nnvdI=


roles Array of Object

Information about the local and referenced external roles to which the user belongs.

Example: [{"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13","name": "PUBLIC","type": "SYSTEM"},{"id": "43dce6d7-40ff-4afa-9901-71c30eb92744","name": "ADMIN","type": "SYSTEM"}]


source String

Information about how the user was created.

  • external: User was imported with an external service like Microsoft Azure Active Directory, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
  • local: User was created manually in the Dremio user interface (UI) or with the User API.

Example: local


active Boolean

If the user account is active in Dremio, the value is true. Otherwise, the value is false. The active value is set to true when the user is created and only changes if the user's status changes in external System for Cross-domain Identity Management (SCIM) provisioning. When the user is activated in the SCIM application, Dremio sets the value to true. When the user is deactivated in the SCIM application, Dremio sets the value to false.

Example: true

Attributes of the roles Object

id String (UUID)

Unique identifier of the role.

Example: 43dce6d7-40ff-4afa-9901-71c30eb92744


name String

Name of the role.

Example: ADMIN


type String

Origin of the role.

  • INTERNAL: Role was created in the Dremio user interface (UI) or with the Role API.
  • EXTERNAL: Role was imported from an external service like Microsoft Azure Active Directory, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
  • SYSTEM: Role was predefined in Dremio.

Example: SYSTEM

Creating a User

Create a Dremio user.

Method and URL
POST /api/v3/user

Parameters

name Body   String

Username for the Dremio user account. The name must be unique and cannot be updated after the user is created.

Example: dremio


firstName Body   String   Optional

User's first name.

Example: Dre


lastName Body   String   Optional

User's last name.

Example: Mio


email Body   String   Optional

User's email address.

Example: user@dremio.com


roles Body   Array of Object   Optional

Information about the roles to which the user should be assigned. All users are assigned to the PUBLIC role by default.

Example: [{"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13","name": "PUBLIC","type": "SYSTEM"},{"id": "43dce6d7-40ff-4afa-9901-71c30eb92744","name": "ADMIN","type": "SYSTEM"}]

Parameters of the roles Object

id Body   String (UUID)

Unique identifier of the role.

Example: 43dce6d7-40ff-4afa-9901-71c30eb92744


name Body   String

Name of the role. All users are assigned to the PUBLIC role by default.

Example: ADMIN


type Body   String   Optional

Origin of the role.

  • INTERNAL: Role was created in the Dremio user interface (UI) or with the Role API.
  • EXTERNAL: Role was imported from an external service like Microsoft Azure Active Directory, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
  • SYSTEM: Role was predefined in Dremio.

Example: SYSTEM

Example Request
curl -X POST 'https://{hostname}/api/v3/user' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "dremio",
"firstName": "Dre",
"lastName": "Mio",
"email": "user@dremio.com",
"roles": [
{
"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
"name": "PUBLIC",
"type": "SYSTEM"
},
{
"id": "43dce6d7-40ff-4afa-9901-71c30eb92744",
"name": "ADMIN",
"type": "SYSTEM"
}
]
}'
Example Response
{
"@type": "EnterpriseUser",
"id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
"name": "dremio",
"firstName": "Dre",
"lastName": "Mio",
"email": "user@dremio.com",
"tag": "EuCNt1nnvdI=",
"roles": [
{
"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
"name": "PUBLIC",
"type": "SYSTEM"
},
{
"id": "43dce6d7-40ff-4afa-9901-71c30eb92744",
"name": "ADMIN",
"type": "SYSTEM"
}
],
"source": "external",
"active": true
}

Response Status Codes

200   OK

204   No Content

400   Bad Request

401   Unauthorized

404   Not Found

405   Method Not Allowed

500   Internal Server Error

Retrieving a User by ID

Retrieve a specific user by the user's ID.

Method and URL
GET /api/v3/user/{id}

Parameters

id Path   String

Unique identifier of the user you want to retrieve.

Example: b9dbebc7-bc3b-4d56-9154-31762ab65a43

Example Request
curl -X GET 'https://{hostname}/api/v3/user/b9dbebc7-bc3b-4d56-9154-31762ab65a43' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response
{
"@type": "EnterpriseUser",
"id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
"name": "dremio",
"firstName": "Dre",
"lastName": "Mio",
"email": "user@dremio.com",
"tag": "EuCNt1nnvdI=",
"roles": [
{
"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
"name": "PUBLIC",
"type": "SYSTEM"
},
{
"id": "43dce6d7-40ff-4afa-9901-71c30eb92744",
"name": "ADMIN",
"type": "SYSTEM"
}
],
"source": "local",
"active": true
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

500   Internal Server Error

Retrieving a User by Name

Retrieve a specific user by the user's name.

Method and URL
GET /api/v3/user/by-name/{name}

Parameters

name Path   String

User name of the user you want to retrieve. User names are case-insensitive. If the user name includes special characters for a URL, such as spaces, use URL encoding to replace the special characters with their UTF-8-equivalent characters. For example, "Dremio University" should be Dremio%20University in the URL path.

Example: b9dbebc7-bc3b-4d56-9154-31762ab65a43

Example Request
curl -X GET 'https://{hostname}/api/v3/user/by-name/dremio' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

When you retrieve a user by name, the response is an abbreviated user object that does not include the @type, roles, or source attributes:

Example Response
{
"id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
"name": "dremio",
"firstName": "Dre",
"lastName": "Mio",
"email": "user@dremio.com",
"tag": "EuCNt1nnvdI=",
"active": true
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

500   Internal Server Error

Updating a User

Update the specified user.

Method and URL
PUT /api/v3/user/{id}

Parameters

id Path   String (UUID)

Unique identifier of the user you want to update.

Example: 1990e713-3cd2-458c-89e1-68995c2c1047


id Body   String (UUID)

Unique identifier of the user you want to update.

Example: 1990e713-3cd2-458c-89e1-68995c2c1047


tag Body   String

Unique identifier of the user version to update. Dremio uses the tag to ensure that you are updating the most recent version of the user.

Example: BNGRmgfEnDg=


name Body   String

Name of the user.

Example: dremio


firstName Body   String   Optional

User's first name.

Example: Dre


lastName Body   String   Optional

User's last name.

Example: Mio


email Body   String   Optional

User's email address.

Example: user@dremio.com


roles Body   String   Optional

Information about the roles to which the user should be assigned. All users are assigned to the PUBLIC role by default.

Example: [{"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13","name": "PUBLIC","type": "SYSTEM"},{"id": "43dce6d7-40ff-4afa-9901-71c30eb92744","name": "ADMIN","type": "SYSTEM"}]

Parameters of the roles Object

id Body   String (UUID)

Unique identifier of the role.

Example: 43dce6d7-40ff-4afa-9901-71c30eb92744


name Body   String

Name of the role. All users are assigned to the PUBLIC role by default.

Example: VIEWER


type Body   String   Optional

Origin of the role.

  • INTERNAL: Role was created in the Dremio user interface (UI) or with the Role API.
  • EXTERNAL: Role was imported from an external service like Microsoft Azure Active Directory, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
  • SYSTEM: Role was predefined in Dremio.

Enum: SYSTEM, INTERNAL, EXTERNAL

Example: INTERNAL

Example Request
curl -X PUT 'https://{hostname}/api/v3/user/b9dbebc7-bc3b-4d56-9154-31762ab65a43' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
"name": "dremio",
"tag": "EuCNt1nnvdI=",
"firstName": "Dremio",
"lastName": "User",
"email": "user@dremio.com",
"roles": [
{
"id": "2f498015-9211-4b15-8fc0-493628ae7b6e",
"name": "VIEWER"
}
]
}'
Example Response
{
"@type": "EnterpriseUser",
"id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
"name": "dremio",
"firstName": "Dremio",
"lastName": "User",
"email": "user@dremio.com",
"tag": "BE1LYg3cmAk=",
"roles": [
{
"id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
"name": "PUBLIC",
"type": "SYSTEM"
},
{
"id": "2f498015-9211-4b15-8fc0-493628ae7b6e",
"name": "VIEWER",
"type": "INTERNAL"
}
],
"source": "external",
"active": true
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

405   Method Not Allowed

500   Internal Server Error

Deleting a User

Delete the specified user.

Method and URL
DELETE /api/v3/user/{id}?version={tag}

Parameters

id Path   String (UUID)

Unique identifier of the user that you want to delete. You can only delete users that are not currently logged in to Dremio.

Example: b9dbebc7-bc3b-4d56-9154-31762ab65a43


version Query   String

Unique identifier of the user version to delete. The version value is the user's tag, which you can find in the response for a request to Retrieve a User by ID or Retrieve a User by Name. Dremio uses the version value to ensure that you are deleting the most recent version of the user. If you provide an incorrect tag, the response includes an error message that lists the correct tag for the specified user ID.

Example: ?version=BE1LYg3cmAk=

Example Request
curl -X DELETE 'https://{hostname}/api/v3/user/b9dbebc7-bc3b-4d56-9154-31762ab65a43?version=BE1LYg3cmAk=' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response
No response

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

405   Method Not Allowed