Skip to main content
Version: 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