On this page

    Role enterprise

    Use the Role API to manage roles.

    Role Object
    {
      "id": "957a8af5-9211-4bc5-9fe5-1a44ff30304d",
      "name": "Temporary Testing",
      "type": "INTERNAL",
      "roles": [
        {
          "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7",
          "name": "qa_team1",
          "type": "INTERNAL"
        },
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248",
          "name": "prod_testing",
          "type": "INTERNAL"
        }
      ],
      "memberCount": 3,
      "description": "Role for testing the new feature"
    }
    

    Role Attributes

    id

    String (UUID)

    Unique identifier of the role.

    Example 957a8af5-9211-4bc5-9fe5-1a44ff30304d


    name

    String

    User-provided name of the role.

    Example Temporary Testing


    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 INTERNAL


    roles

    [Object]

    Information about the roles to which the role belongs.

    Example [ { "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7", "name": "SELECT and CREATE", "type": "INTERNAL" }, { "id": "f8426061-8413-46ec-a84d-1b481a97b248", "name": "VIEW", "type": "INTERNAL" } ]


    memberCount

    Integer

    Number of users and roles that are members of the role.

    Example 3


    description

    String

    User-provided description of the role.

    Example Role for testing the new feature

    roles

    id

    String (UUID)

    Unique identifier of the role.

    Example 6f87a9c5-d733-4935-8331-875a4a8e09d7


    name

    String

    Name of the role.

    Example SELECT and CREATE


    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 INTERNAL

    Creating a Role

    Create a Dremio role.

    Method and URL
    POST /api/v3/role
    

    Parameters

    name

    body

    String

    Name for the role. The role name must be unique and cannot be updated after the role is created.

    Example Temporary Testing


    roles

    body

    [Object]

    Optional

    Information about the roles to which the role should be assigned.

    Example [ { "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7" }, { "id": "f8426061-8413-46ec-a84d-1b481a97b248" } ]


    description

    body

    String

    Optional

    Description for the role.

    Example Role for testing the new feature

    roles

    id

    body

    String (UUID)

    Unique identifier of the role to which the role you create should be assigned.

    Example 6f87a9c5-d733-4935-8331-875a4a8e09d7


    name

    body

    String

    Optional

    Name of the role to which the role you create should be assigned.

    Example qa_team1


    Example Request
    curl -X POST 'https://{DREMIO_ORIGIN}/api/v3/role' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "name": "Temporary Testing",
      "roles": [
        {
          "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7"
        },
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248"
        }
      ],
      "description": "Role for testing the new feature"
    }'
    
    Example Response
    {
      "id": "957a8af5-9211-4bc5-9fe5-1a44ff30304d",
      "name": "Temporary Testing",
      "type": "INTERNAL",
      "roles": [
        {
          "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7",
          "name": "qa_team1",
          "type": "INTERNAL"
        },
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248",
          "name": "prod_testing",
          "type": "INTERNAL"
        }
      ],
      "memberCount": 0,
      "description": "Role for testing the new feature"
    }
    

    Response Status Codes

    200

    OK

    400

    Bad Request

    401

    Unauthorized

    404

    Not Found

    405

    Method Not Allowed


    Retrieving a Role by ID

    Retrieve a specific role by the role’s ID.

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

    Parameters

    id

    path

    String (UUID)

    Unique identifier of the role you want to retrieve.

    Example 957a8af5-9211-4bc5-9fe5-1a44ff30304d


    Example Request
    curl -X GET 'https://{DREMIO_ORIGIN}/api/v3/role/957a8af5-9211-4bc5-9fe5-1a44ff30304d' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json'
    
    Example Response
    {
      "id": "957a8af5-9211-4bc5-9fe5-1a44ff30304d",
      "name": "Temporary Testing",
      "type": "INTERNAL",
      "roles": [
        {
          "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7",
          "name": "qa_team1",
          "type": "INTERNAL"
        },
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248",
          "name": "prod_testing",
          "type": "INTERNAL"
        }
      ],
      "memberCount": 3,
      "description": "Role for testing the new feature"
    }
    

    Response Status Codes

    200

    OK

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error


    Retrieving a Role by Name

    Retrieve a specific role by the role’s name.

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

    Parameters

    name

    path

    String

    Name of the role you want to retrieve. The role name is case-insensitive. URI-encode the name to replace special characters with their UTF-8 characters, such as %3A for a colon and %20 for a space.

    Example Temporary%20Testing


    Example Request
    curl -X GET 'https://{DREMIO_ORIGIN}/api/v3/role/by-name/Temporary%20Testing' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json'
    
    Example Response
    {
      "id": "957a8af5-9211-4bc5-9fe5-1a44ff30304d",
      "name": "Temporary Testing",
      "type": "INTERNAL",
      "roles": [
        {
          "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7",
          "name": "qa_team1",
          "type": "INTERNAL"
        },
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248",
          "name": "prod_testing",
          "type": "INTERNAL"
        }
      ],
      "memberCount": 3,
      "description": "Role for testing the new feature"
    }
    

    Response Status Codes

    200

    OK

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error


    Updating a Role

    Update the specified role.

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

    Parameters

    id

    path

    String (UUID)

    Unique identifier of the role you want to update.

    Example 957a8af5-9211-4bc5-9fe5-1a44ff30304d


    id

    body

    String (UUID)

    Unique identifier of the role you want to update.

    Example 957a8af5-9211-4bc5-9fe5-1a44ff30304d


    name

    body

    String

    Name of the role.

    Example Temporary Testing


    roles

    body

    [Object]

    Optional

    Information about the roles to which the role should be assigned. If you omit an existing role in a PUT request, Dremio removes the role. To keep all existing roles while making other updates, include all existing roles in the PUT request.

    Example [ { "id": "f8426061-8413-46ec-a84d-1b481a97b248" } ]


    description

    body

    String

    Optional

    Description to use for the role. If you omit the description in a PUT request, Dremio removes the existing description. To keep the existing description while making other updates, include the description in the PUT request.

    Example Role for viewing the new feature

    roles

    id

    body

    String (UUID)

    Unique identifier of the role to which the role you update should be assigned.

    Example f8426061-8413-46ec-a84d-1b481a97b248


    name

    body

    String

    Optional

    Name of the role to which the role you update should be assigned.

    Example prod_testing


    Example Request
    curl -X PUT 'https://{DREMIO_ORIGIN}/api/v3/role/957a8af5-9211-4bc5-9fe5-1a44ff30304d' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "id": "957a8af5-9211-4bc5-9fe5-1a44ff30304d",
      "name": "Temporary Testing",
      "roles": [
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248"
        }
      ],
      "description": "Role for viewing the new feature"
    }'
    
    Example Response
    {
      "id": "957a8af5-9211-4bc5-9fe5-1a44ff30304d",
      "name": "Temporary Testing",
      "type": "INTERNAL",
      "roles": [
        {
          "id": "f8426061-8413-46ec-a84d-1b481a97b248",
          "name": "prod_testing",
          "type": "INTERNAL"
        }
      ],
      "memberCount": 3,
      "description": "Role for viewing the new feature"
    }
    

    Response Status Codes

    200

    OK

    400

    Bad Request

    401

    Unauthorized

    404

    Not Found

    405

    Method Not Allowed


    Add and Remove Role Members

    Add and remove members (roles and users) of the specified role.

    Method and URL
    PATCH /api/v3/role/{id}/member
    

    Parameters

    op

    body

    String

    Action to take for the user or role.

    Enum add , remove

    Example add


    id

    body

    String (UUID)

    Unique identifier of the user or role to add or remove.

    Example 957a8af5-9211-4bc5-9fe5-1a44ff30304d


    type

    body

    String

    Type of member you want to add or remove.

    Enum role , user

    Example role


    The request body is an array of objects. Each object includes the three parameters for a single user or role that you want to add or remove:

    Example Request
    curl -X PATCH 'https://{DREMIO_ORIGIN}/api/v3/role/957a8af5-9211-4bc5-9fe5-1a44ff30304d/member' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json' \
    --data-raw '[
      {
        "op": "add",
        "id": "f8426061-8413-46ec-a84d-1b481a97b248",
        "type": "role"
      },
      {
        "op": "add",
        "id": "671cdeb8-1af9-45b6-98ee-8ca1e0543a38",
        "type": "user"
      },
      {
        "op": "remove",
        "id": "6f87a9c5-d733-4935-8331-875a4a8e09d7",
        "type": "role"
      },
      {
        "op": "remove",
        "id": "614a6938-7a69-4f7c-ab96-00b50addb1f9",
        "type": "user"
      }
    ]'
    
    Example Response
    No response
    

    Response Status Codes

    204

    No Content

    400

    Bad Request

    401

    Unauthorized

    404

    Not Found

    405

    Method Not Allowed


    Deleting a Role

    Delete the specified role.

    Method and URL
    DELETE /api/v3/role/{id}
    

    Parameters

    id

    path

    String (UUID)

    Unique identifier of the role that you want to delete.

    Note:

    It is not possible to delete a system role, like ADMIN or PUBLIC. Requests to delete a system role result in a 404 Not Found response.

    Example 957a8af5-9211-4bc5-9fe5-1a44ff30304d


    Example Request
    curl -X DELETE 'https://{DREMIO_ORIGIN}/api/v3/role/957a8af5-9211-4bc5-9fe5-1a44ff30304d' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json'
    
    Example Response
    No response
    

    Response Status Codes

    204

    No Content

    401

    Unauthorized

    404

    Not Found

    405

    Method Not Allowed