Roles

Use the Roles API to create, retrieve, update, and delete roles, and manage role members and parent role assignments.

Role Object

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DATA_ENGINEER",
  "type": "INTERNAL",
  "description": "Role for data engineering team"
}

Role Attributes

id String (UUID)

The unique identifier of the role. This field is read-only.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

name String

The name of the role. This field cannot be changed after creation.

Example: DATA_ENGINEER

type String

Origin of the role. This field is read-only.

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 or a System for Cross-domain Identity Management (SCIM) provider.
SYSTEM: Role was predefined in Dremio.

Example: INTERNAL

description String

A description of the role.

Example: Role for data engineering team

List Roles

List all roles in the organization.

Method and URL

GET /v0/roles

Parameters

filter Query String Optional

A CEL expression to filter results. Filterable attributes: name, id, type, externalId. Supported operators: ==, &&, ||. Supported functions: startsWith, contains.

Example: name == 'DATA_ENGINEER'

maxResults Query Integer Optional

Maximum number of results to return per page. Minimum: 1. Maximum: 1000.

Example: 50

pageToken Query String Optional

Token specifying which page to return. Do not change other query parameters when using pageToken.

orderBy Query String Optional

Attribute to order results by. Defaults to ascending order. For descending order, prefix the attribute name with -.

Example: name

Example Request

curl -X GET 'https://api.dremio.cloud/v0/roles' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "DATA_ENGINEER",
      "type": "INTERNAL",
      "description": "Role for data engineering team"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "ANALYST",
      "type": "INTERNAL",
      "description": "Role for analysts"
    }
  ],
  "totalResults": 2
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

500 Internal Server Error

Create a Role

Create a role in the organization.

Method and URL

POST /v0/roles

Parameters

name Body String

The name of the role.

Example: DATA_ENGINEER

description Body String Optional

A description of the role.

Example: Role for data engineering team

Example Request

curl -X POST 'https://api.dremio.cloud/v0/roles' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json' \
-d '{"name": "DATA_ENGINEER", "description": "Role for data engineering team"}'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DATA_ENGINEER",
  "type": "INTERNAL",
  "description": "Role for data engineering team"
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Retrieve a Role by Name

Get a role by name.

Method and URL

GET /v0/roles/names/{roleName}

Parameters

roleName Path String

The name of the role to retrieve.

Example: DATA_ENGINEER

Example Request

curl -X GET 'https://api.dremio.cloud/v0/roles/names/DATA_ENGINEER' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DATA_ENGINEER",
  "type": "INTERNAL",
  "description": "Role for data engineering team"
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Retrieve a Role by ID

Get a role by ID.

Method and URL

GET /v0/roles/{roleId}

Parameters

roleId Path String (UUID)

The ID of the role to retrieve.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Example Request

curl -X GET 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DATA_ENGINEER",
  "type": "INTERNAL",
  "description": "Role for data engineering team"
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Update a Role

Update a role. Only the description field is updatable.

Method and URL

PUT /v0/roles/{roleId}

Parameters

roleId Path String (UUID)

The ID of the role to update.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

id Path String (UUID)

The ID of the role to update.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

description Body String Optional

The updated description for the role.

Example: Role for the data engineering team

Example Request

curl -X PUT 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json' \
-d '{"id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890","description": "Role for the data engineering team"}'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "DATA_ENGINEER",
  "type": "INTERNAL",
  "description": "Role for the data engineering team"
}

Response Status Codes

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Deleting a Role

Delete a role.

Method and URL

DELETE /v0/roles/{roleId}

Parameters

roleId Path String (UUID)

The ID of the role to delete.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Example Request

curl -X DELETE 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

No response

Response Status Codes

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

List Parent Roles for a Role

List the roles this role is a direct member of. This does not include transitive role memberships.

Method and URL

GET /v0/roles/{roleId}/parent-roles

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

maxResults Query Integer Optional

Maximum number of results to return per page. Minimum: 1. Maximum: 1000.

Example: 50

pageToken Query String Optional

Token specifying which page to return. Do not change other query parameters when using pageToken.

Example Request

curl -X GET 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/parent-roles' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "name": "SENIOR_DATA_ENGINEER",
      "type": "INTERNAL",
      "description": "Role for Senior Data Engineers"
    }
  ],
  "totalResults": 1
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

500 Internal Server Error

Add a Parent Role to a Role

Add a parent role to the role's list of parent roles.

Method and URL

POST /v0/roles/{roleId}/parent-roles

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

id Body String (UUID)

The ID of the parent role to add.

Example: c3d4e5f6-a7b8-9012-cdef-345678901234

Example Request

curl -X POST 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/parent-roles' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json' \
-d '{"id": "c3d4e5f6-a7b8-9012-cdef-345678901234"}'

Example Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}

Response Status Codes

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Update Parent Roles for a Role

Add and remove parent roles for a role in a single request.

Method and URL

PATCH /v0/roles/{roleId}/parent-roles

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

addRoles Body Array of String (UUID) Optional

List of role IDs to add as parent roles.

Example: ["c3d4e5f6-a7b8-9012-cdef-345678901234"]

removeRoles Body Array of String (UUID) Optional

List of role IDs to remove from parent roles.

Example: ["d4e5f6a7-b8c9-0123-def4-567890123456"]

Example Request

curl -X PATCH 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/parent-roles' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json' \
-d '{
  "addRoles": ["c3d4e5f6-a7b8-9012-cdef-345678901234"],
  "removeRoles": ["d4e5f6a7-b8c9-0123-def4-567890123456"]
}'

Example Response

{
  "addedRoles": ["c3d4e5f6-a7b8-9012-cdef-345678901234"],
  "removedRoles": ["d4e5f6a7-b8c9-0123-def4-567890123456"]
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Remove a Parent Role from a Role

Remove a parent role from the role's list of parent roles.

Method and URL

DELETE /v0/roles/{roleId}/parent-roles/{parentRoleId}

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

parentRoleId Path String (UUID)

The ID of the parent role to remove.

Example: c3d4e5f6-a7b8-9012-cdef-345678901234

Example Request

curl -X DELETE 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/parent-roles/c3d4e5f6-a7b8-9012-cdef-345678901234' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

No response

Response Status Codes

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

List Members of a Role

List the direct members of a role. Members can be users or other roles. This does not include transitive memberships.

Method and URL

GET /v0/roles/{roleId}/members

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

maxResults Query Integer Optional

Maximum number of results to return per page. Minimum: 1. Maximum: 1000.

Example: 50

pageToken Query String Optional

Token specifying which page to return. Do not change other query parameters when using pageToken.

Example Request

curl -X GET 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "type": "USER"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "type": "ROLE"
    }
  ],
  "totalResults": 2
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Add a Member to a Role

Add a user or role as a member of a role.

Method and URL

POST /v0/roles/{roleId}/members

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

id Body String (UUID)

The ID of the user or role to add as a member.

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

type Body String

The type of member to add.

Enum: USER, ROLE

Example: USER

Example Request

curl -X POST 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json' \
-d '{"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "USER"}'

Example Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "USER"
}

Response Status Codes

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Update Members of a Role

Add and remove role members in a single request.

Method and URL

PATCH /v0/roles/{roleId}/members

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

addRoles Body Array of String (UUID) Optional

List of role IDs to add as members.

Example: ["b2c3d4e5-f6a7-8901-bcde-f23456789012"]

removeRoles Body Array of String (UUID) Optional

List of role IDs to remove from members.

Example: ["c3d4e5f6-a7b8-9012-cdef-345678901234"]

addUsers Body Array of String (UUID) Optional

List of user IDs to add as members.

Example: ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]

removeUsers Body Array of String (UUID) Optional

List of user IDs to remove from members.

Example: ["d4e5f6a7-b8c9-0123-def4-567890123456"]

Example Request

curl -X PATCH 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json' \
-d '{
  "addUsers": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "removeUsers": ["d4e5f6a7-b8c9-0123-def4-567890123456"],
  "addRoles": ["b2c3d4e5-f6a7-8901-bcde-f23456789012"],
  "removeRoles": ["c3d4e5f6-a7b8-9012-cdef-345678901234"]
}'

Example Response

{
  "addedUsers": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "removedUsers": ["d4e5f6a7-b8c9-0123-def4-567890123456"],
  "addedRoles": ["b2c3d4e5-f6a7-8901-bcde-f23456789012"],
  "removedRoles": ["c3d4e5f6-a7b8-9012-cdef-345678901234"]
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Remove a Member from a Role

Remove a member from a role.

Method and URL

DELETE /v0/roles/{roleId}/members/{memberId}

Parameters

roleId Path String (UUID)

The ID of the role.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

memberId Path String (UUID)

The ID of the member to remove.

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Example Request

curl -X DELETE 'https://api.dremio.cloud/v0/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/members/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
-H 'Authorization: Bearer <access token>' \
-H 'Content-Type: application/json'

Example Response

No response

Response Status Codes

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Role Attributes​

List Roles​

Parameters​

Response Status Codes​

Create a Role​

Parameters​

Response Status Codes​

Retrieve a Role by Name​

Parameters​

Response Status Codes​

Retrieve a Role by ID​

Parameters​

Response Status Codes​

Update a Role​

Parameters​

Response Status Codes​

Deleting a Role​

Parameters​

Response Status Codes​

List Parent Roles for a Role​

Parameters​

Response Status Codes​

Add a Parent Role to a Role​

Parameters​

Response Status Codes​

Update Parent Roles for a Role​

Parameters​

Response Status Codes​

Remove a Parent Role from a Role​

Parameters​

Response Status Codes​

List Members of a Role​

Parameters​

Response Status Codes​

Add a Member to a Role​

Parameters​

Response Status Codes​

Update Members of a Role​

Parameters​

Response Status Codes​

Remove a Member from a Role​

Parameters​

Response Status Codes​

Role Attributes

List Roles

Parameters

Response Status Codes

Create a Role

Parameters

Response Status Codes

Retrieve a Role by Name

Parameters

Response Status Codes

Retrieve a Role by ID

Parameters

Response Status Codes

Update a Role

Parameters

Response Status Codes

Deleting a Role

Parameters

Response Status Codes

List Parent Roles for a Role

Parameters

Response Status Codes

Add a Parent Role to a Role

Parameters

Response Status Codes

Update Parent Roles for a Role

Parameters

Response Status Codes

Remove a Parent Role from a Role

Parameters

Response Status Codes

List Members of a Role

Parameters

Response Status Codes

Add a Member to a Role

Parameters

Response Status Codes

Update Members of a Role

Parameters

Response Status Codes

Remove a Member from a Role

Parameters

Response Status Codes