On this page

    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

    String

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

    Example dremio


    firstName

    String

    Optional

    User's first name.

    Example Dre


    lastName

    String

    Optional

    User's last name.

    Example Mio


    email

    String

    Optional

    User's email address.

    Example user@dremio.com


    roles

    [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

    String (UUID)

    Unique identifier of the role.

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


    name

    String

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

    Example ADMIN


    type

    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: _dremio{tokenstring}' \
    --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: _dremio{tokenstring}' \
    --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. URI-encode the name to replace special characters with their UTF-8 equivalents, such as %3A for a colon and %20 for a space.

    Example dremio


    Example Request
    curl -X GET 'https://{DREMIO_ORIGIN}/api/v3/user/by-name/dremio' \
    --header 'Authorization: _dremio{tokenstring}' \
    --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

    String

    Name of the user.

    Example dremio


    firstName

    String

    Optional

    User's first name.

    Example Dre


    lastName

    String

    Optional

    User's last name.

    Example Mio


    email

    String

    Optional

    User's email address.

    Example user@dremio.com


    roles

    [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

    String (UUID)

    Unique identifier of the role.

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


    name

    String

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

    Example VIEWER


    type

    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: _dremio{tokenstring}' \
    --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: _dremio{tokenstring}' \
    --header 'Content-Type: application/json'
    
    Example Response
    No response
    

    Response Status Codes

    200

    OK

    401

    Unauthorized

    404

    Not Found

    405

    Method Not Allowed