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: Bearer <PersonalAccessToken>' \
--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: Bearer <PersonalAccessToken>' \
--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. If the role 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 Temporary%20Testing

Example Request

curl -X GET 'https://{DREMIO_ORIGIN}/api/v3/role/by-name/Temporary%20Testing' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--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: Bearer <PersonalAccessToken>' \
--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: Bearer <PersonalAccessToken>' \
--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: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Example Response

No response

Response Status Codes

204

No Content

401

Unauthorized

404

Not Found

405

Method Not Allowed

---