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
[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 URLPOST /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
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"
}'
{
"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 URLGET /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'
{
"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 URLGET /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'
{
"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 URLPUT /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
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"
}'
{
"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 URLPATCH /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 Requestcurl -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"
}
]'
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 URLDELETE /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'
No response
Response Status Codes
204
No Content
401
Unauthorized
404
Not Found
405
Method Not Allowed