Version: current [26.x]

User Enterprise

The User API manages local and SSO users and service users.

Users
Service Users

User Object

{
  "@type": "EnterpriseUser",
  "id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
  "name": "dremio",
  "firstName": "Dre",
  "lastName": "Mio",
  "email": "[email protected]",
  "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",
  "identityType": "REGULAR_USER",
  "active": true
}

Service User Object

{
  "@type": "EnterpriseUser",
  "id": "5263eb65-5fba-406b-9539-8627240adb8e",
  "name": "service_user",
  "roles": [
    {
      "id": "1934dbb5-c57b-49fa-b7da-e709c1716c2f",
      "name": "PUBLIC",
      "type": "SYSTEM"
    },
    {
      "id": "563fa12c-fa11-4753-9025-f1089ab8f1bc",
      "name": "ADMIN",
      "type": "SYSTEM"
    }
  ],
  "source": "local",
  "active": true,
  "identityType": "SERVICE_USER",
  "oauthClientId": "61d00e34-a938-4b80-9a98-063fc723bd6d"
}

Attributes

@type String

Type of user. Valid values are:

EnterpriseUser: Created by Dremio Enterprise Edition.
User: Created by Dremio Community Edition.

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. Available only with identityType REGULAR_USER.

Example: Dre

lastName String

User's last name. Available only with identityType REGULAR_USER.

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 Entra ID, email is the work email address in the user's Microsoft Entra ID profile. Available only with identityType REGULAR_USER.

Example: [email protected]

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. Available only with identityType REGULAR_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 Entra ID, 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

identityType String

The type of user:

REGULAR_USER (Default): An individual person.
SERVICE_USER: A machine or application user.

Example: REGULAR_USER

oauthClientId String

The unique OAuth client identifier generated by Dremio for service user authentication. This client ID is used in OAuth client credentials flows to obtain access tokens for API authentication. Available only for identityType SERVICE_USER.

Example: 88d7c3cc-cab5-4ab1-917c-e075265501dd

Attributes of Objects in the `roles` Array

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 Entra ID, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
SYSTEM: Role was predefined in Dremio.

Example: SYSTEM

List Users

Method and URL

GET /api/v3/user

Parameters

filter Query Object Optional

Filter the user list:

User Fields	Functions	Operators
`id` `name` `firstName` `lastName` `email` `identityType`	`startsWith()` `contains()`	'==' encoded as `%3D%3D` (equals) '&&' encoded as `%26%26` (logical and) '\|\|' encoded as `%7C%7C` (logical or)

The filter parameter value must be URL-encoded. Examples:

?filter=name%3D%3D%27john%2Edoe%27 evaluates to "name=='john.doe'"
?filter=email%2EstartsWith%28%27admin%27%29 evaluates to "email.startsWith('admin')"
?filter=firstName%2Econtains%28%27smith%27%29%26%26identityType%3D%3D%27SERVICE_USER%27 evaluates to "firstName.contains('smith')&&identityType=='SERVICE_USER'"

For more information, see filter Query Parameter.

Example

Request

curl -X GET "https://{hostname}/api/v3/user?filter=firstName%3D%3D%27dre%27%26%26identityType%3D%3D%27REGULAR_USER%27" \
  --header 'Authorization: Bearer C4bVdq0MSFyHW5etR9WvrQP9WNYdRZdOIePtfw0mRJLUU4cWRQWMEZYbx5RDaA==' \
  --header 'Content-Type: application/json'

Response

{
  "data": [
    {
      "@type": "EnterpriseUser",
      "id": "b5537771-8506-4c8d-8014-6687cf570410",
      "name": "dremio",
      "firstName": "Dre",
      "lastName": "Mio",
      "email": "[email protected]",
      "tag": "zF+ueKESvHU=",
      "roles": [
        {
          "id": "bfc34dbc-f659-4e84-9278-31f7d9375656",
          "name": "PUBLIC",
          "type": "SYSTEM"
        },
        {
          "id": "90fd20a2-9352-4386-a963-fdee15fb5243",
          "name": "ADMIN",
          "type": "SYSTEM"
        }
      ],
      "source": "local",
      "active": true,
      "identityType": "REGULAR_USER"
    }
  ],
  "totalResults": 1
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

Create a 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. Available only for identityType REGULAR_USER.

Example: Dre

lastName Body String Optional

User's last name. Available only for identityType REGULAR_USER.

Example: Mio

email Body String Optional

User's email address. Available only for identityType REGULAR_USER.

Example: [email protected]

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.

Parameters of Objects in the `roles` Array

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 Entra ID, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
SYSTEM: Role was predefined in Dremio.

Example: SYSTEM

Example

Create a User
Create a Service User

Request

curl -X POST 'https://{hostname}/api/v3/user' \
--header 'Authorization: Bearer <dremioAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "dremio",
  "firstName": "Dre",
  "lastName": "Mio",
  "email": "[email protected]",
  "roles": [
    {
      "id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
      "name": "PUBLIC",
      "type": "SYSTEM"
    },
    {
      "id": "43dce6d7-40ff-4afa-9901-71c30eb92744",
      "name": "ADMIN",
      "type": "SYSTEM"
    }
  ]
}'

Response

{
  "@type": "EnterpriseUser",
  "id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
  "name": "dremio",
  "firstName": "Dre",
  "lastName": "Mio",
  "email": "[email protected]",
  "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",
  "identityType": "REGULAR_USER", 
  "active": true
}

Request

curl -X POST 'https://{hostname}/api/v3/user' \
--header 'Authorization: Bearer <dremioAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "api_service_user",
  "description": "Nightly data ingestion", 
  "roles": [
    {
      "id": "8ac1bbca-479c-4c47-87e9-7f946f665c13",
      "name": "PUBLIC",
      "type": "SYSTEM"
    },
    {
      "id": "43dce6d7-40ff-4afa-9901-71c30eb92744",
      "name": "ADMIN",
      "type": "SYSTEM"
    }
  ],
  "identityType": "SERVICE_USER" 
}'

Response

{
  "@type": "EnterpriseUser",
  "id": "090d605c-ba0e-4b42-8831-e10d6fd08101",
  "name": "api_service_user",
  "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,
  "identityType": "SERVICE_USER",
  "oauthClientId": "3f7a9ff7-fd5f-493c-b4f0-8d1a76ceef24"
}

Response Status Codes

200   OK

204   No Content

400   Bad Request

401   Unauthorized

404   Not Found

405   Method Not Allowed

500   Internal Server Error

Retrieve 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://{hostname}/api/v3/user/b9dbebc7-bc3b-4d56-9154-31762ab65a43' \
--header 'Authorization: Bearer <dremioAccessToken>' \
--header 'Content-Type: application/json'

Response

{
  "@type": "EnterpriseUser",
  "id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
  "name": "dremio",
  "firstName": "Dre",
  "lastName": "Mio",
  "email": "[email protected]",
  "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",
  "identityType": "REGULAR_USER", 
  "active": true
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

500   Internal Server Error

Retrieve a User by Name

Use this command to import a user from your integrated identity provider (IdP) by specifying their name.

Method and URL

GET /api/v3/user/by-name/{name}

Parameters

name Path String

Username of the user you want to retrieve. Usernames are case-insensitive. If the username 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: nightly-etl

Example

Request

curl -X GET 'https://{hostname}/api/v3/user/by-name/nightly-etl' \
--header 'Authorization: Bearer <dremioAccessToken>' \
--header 'Content-Type: application/json'

Response

{
  "@type": "EnterpriseUser",
  "id": "5263eb65-5fba-406b-9539-8627240adb8e",
  "name": "service_user",
  "roles": [
    {
      "id": "1934dbb5-c57b-49fa-b7da-e709c1716c2f",
      "name": "PUBLIC",
      "type": "SYSTEM"
    },
    {
      "id": "563fa12c-fa11-4753-9025-f1089ab8f1bc",
      "name": "ADMIN",
      "type": "SYSTEM"
    }
  ],
  "source": "local",
  "active": true,
  "identityType": "SERVICE_USER",
  "oauthClientId": "61d00e34-a938-4b80-9a98-063fc723bd6d"
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

500   Internal Server Error

Update 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. Available only with identityType REGULAR_USER.

Example: BNGRmgfEnDg=

name Body String

Name of the user. Available only with identityType REGULAR_USER.

Example: dremio

firstName Body String Optional

User's first name. Available only with identityType REGULAR_USER.

Example: Dre

lastName Body String Optional

User's last name. Available only with identityType REGULAR_USER.

Example: Mio

email Body String Optional

User's email address. Available only with identityType REGULAR_USER.

Example: [email protected]

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 Objects in the `roles` Array

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 Entra ID, Lightweight Directory Access Protocol (LDAP), or a System for Cross-domain Identity Management (SCIM) provider.
SYSTEM: Role was predefined in Dremio.

Example: INTERNAL

Example

Request

curl -X PUT 'https://{hostname}/api/v3/user/b9dbebc7-bc3b-4d56-9154-31762ab65a43' \
--header 'Authorization: Bearer <dremioAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
  "name": "dremio",
  "tag": "EuCNt1nnvdI=",
  "firstName": "Dremio",
  "lastName": "User",
  "email": "[email protected]",
  "roles": [
    {
      "id": "2f498015-9211-4b15-8fc0-493628ae7b6e",
      "name": "VIEWER"
    }
  ]
}'

Response

{
  "@type": "EnterpriseUser",
  "id": "b9dbebc7-bc3b-4d56-9154-31762ab65a43",
  "name": "dremio",
  "firstName": "Dremio",
  "lastName": "User",
  "email": "[email protected]",
  "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",
  "identityType": "REGULAR_USER",
  "active": true
}

Response Status Codes

200   OK

401   Unauthorized

404   Not Found

405   Method Not Allowed

500   Internal Server Error

Delete a User

Method and URL

DELETE /api/v3/user/{id}

Parameters

id Path String (UUID)

Unique identifier of the user 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

When the identityType is REGULAR_USER, the 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

Delete a User
Delete a Service User

Request

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

A successful request returns an empty response with the HTTP 204 No Content status.

Request

curl -X DELETE 'https://{hostname}/api/v3/user/5263eb65-5fba-406b-9539-8627240adb8e' \
--header 'Authorization: Bearer <dremioAccessToken>' \
--header 'Content-Type: application/json'

A successful request returns an empty response with the HTTP 204 No Content status.

Response Status Codes

204 No Content

401 Unauthorized

404 Not Found

405 Method Not Allowed

Attributes​

Attributes of Objects in the roles Array​

List Users​

Parameters​

Example​

Response Status Codes​

Create a User​

Parameters​

Parameters of Objects in the roles Array​

Example​

Response Status Codes​

Retrieve a User by ID​

Parameters​

Example​

Response Status Codes​

Retrieve a User by Name​

Parameters​

Example​

Response Status Codes​

Update a User​

Parameters​

Parameters of Objects in the roles Array​

Example​

Response Status Codes​

Delete a User​

Parameters​

Example​

Response Status Codes​

Attributes

Attributes of Objects in the `roles` Array

List Users

Parameters

Example

Response Status Codes

Create a User

Parameters

Parameters of Objects in the `roles` Array

Example

Response Status Codes

Retrieve a User by ID

Parameters

Example

Response Status Codes

Retrieve a User by Name

Parameters

Example

Response Status Codes

Update a User

Parameters

Parameters of Objects in the `roles` Array

Example

Response Status Codes

Delete a User

Parameters

Example

Response Status Codes