Skip to main content
Version: current [24.2.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

[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

roles​

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

[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" } ]

roles​

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://{DREMIO_ORIGIN}/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

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 (UUID)

Unique identifier of the user you want to retrieve.

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


Example Request
curl -X GET 'https://{DREMIO_ORIGIN}/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 dremio


Example Request
curl -X GET 'https://{DREMIO_ORIGIN}/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

[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" } ]

roles​

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://{DREMIO_ORIGIN}/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://{DREMIO_ORIGIN}/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