Grants

Use the Catalog API to grant privileges to users and roles on specific catalog objects.

note

Use the Privileges endpoint to retrieve lists of the privileges that are available on each type of catalog object.

Use the Dremio console or SQL commands to grant privileges on Arctic catalog sources. The API does not support granting privileges on Arctic catalog sources.

Grants Object

{
  "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
  "availablePrivileges": [
    "ALTER",
    "DELETE",
    "INSERT",
    "MANAGE_GRANTS",
    "SELECT",
    "TRUNCATE",
    "UPDATE"
  ],
  "grants": [
    {
      "privileges": [
        "ALTER",
        "SELECT",
        "MANAGE_GRANTS"
      ],
      "granteeType": "USER",
      "id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0",
      "name": "jeansmith",
      "firstName": "Jean",
      "lastName": "Smith",
      "email": "jean_smith@example.com"
    },
    {
      "privileges": [
        "ALTER",
        "SELECT"
      ],
      "granteeType": "ROLE",
      "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
      "name": "examplerole"
    }
  ]
}

Grants Attributes

id String

Unique identifier of the Dremio catalog object.

Example: 7f1c4660-cd7b-40d0-97d1-b8a6f431cbda

---

availablePrivileges Array of String

List of available privileges on the catalog object. Read Privileges for more information.

Example: ["ALTER","DELETE","INSERT","MANAGE_GRANTS","SELECT","TRUNCATE","UPDATE"]

---

grants Array of Object

Information about the privileges and grantees for the catalog object. If the grants array is empty, there are no explicit grants for the object. An empty grants array does not mean no users have access to the object at all. For example, admin users implicitly have all privileges on all catalog objects, owners implicitly have all privileges on everything they own, and children objects inherit the grants for their parent objects.

Example: [{"privileges": ["ALTER","SELECT","MANAGE_GRANTS"],"granteeType": "USER","id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0","name": "jeansmith","firstName": "Jean","lastName": "Smith","email": "jean_smith@example.com"},{"privileges": ["ALTER","SELECT"],"granteeType": "ROLE","id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889","name": "examplerole"}]

Attributes of the grants Object

privileges Array of String

List of privileges granted to the user or role. Read Privileges.

Example: ["ALTER","SELECT","MANAGE_GRANTS"]

---

granteeType String

Type of grantee.

Enum: USER, ROLE

Example: USER

---

id String

Unique identifier of the user or role.

Example: 27937a63-e7e5-4478-8d3c-4ad3f20d43c0

---

name String

Name of the user or role.

Example: jeansmith

---

firstName String

The user's first name. Not included if the object is a role.

Example: Jean

---

lastName String

The user's last name. Not included if the object is a role.

Example: Smith

---

email String

The user's email address. Not included if the object is a role.

Example: jean_smith@example.com

Creating or Updating Grants on a Catalog Object

Create or update the privileges granted to users and roles on the specified catalog object.

note

You must have the MANAGE GRANTS privilege to create or update grants on catalog objects.

Use the Dremio console or SQL commands to grant privileges on Arctic catalog sources. The API does not support granting privileges on Arctic catalog sources.

Method and URL

PUT /v0/projects/{project-id}/catalog/{id}/grants

Parameters

project-id Path   String (UUID)

Unique identifier of the project that contains the catalog object whose grants you want to create or update.

Example: 601a5d10-5fa6-4963-a2a9-157a137558e5

---

id Path   String (UUID)

Unique identifier of the Dremio catalog object.

Example: 7f1c4660-cd7b-40d0-97d1-b8a6f431cbda

---

grants Body   Array of Object

Array of objects that specify which users and roles should have privileges on the catalog object, as well as the specific privileges for each user and role. May include objects for users, roles, or both.

Example: [{"privileges": ["ALTER","SELECT","MANAGE_GRANTS"],"granteeType": "USER","id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0"},{"privileges": ["SELECT","ALTER"],"granteeType": "ROLE","id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889"}]

Parameters of the grants Object

privileges Body   Array of String

List of privileges to grant to the user or role. Use the Privileges endpoint to retrieve a list of available privileges on the catalog object type. Read Privileges for more information.

Example: ["ALTER","SELECT","MANAGE_GRANTS"]

---

granteeType Body   String

Type of grantee.

Enum: USER, ROLE

Example: USER

---

id Body   String

Unique identifier of the user or role.

Example: 27937a63-e7e5-4478-8d3c-4ad3f20d43c0

Example Request

curl -X PUT 'https://api.dremio.cloud/v0/projects/601a5d10-5fa6-4963-a2a9-157a137558e5/catalog/7f1c4660-cd7b-40d0-97d1-b8a6f431cbda/grants' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grants": [
    {
      "privileges": [
        "ALTER",
        "SELECT",
        "MANAGE_GRANTS"
      ],
      "granteeType": "USER",
      "id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0"
    },
    {
      "privileges": [
        "SELECT",
        "ALTER"
      ],
      "granteeType": "ROLE",
      "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889"
    }
  ]
}'

Example Response

No response

Response Status Codes

204   No Content

401   Unauthorized

404   Not Found

Retrieving Privileges and Grantees on a Catalog Object

Retrieve information about the privileges granted to users and roles on the specified catalog object.

note

You must have the MANAGE GRANTS privilege to retrieve grants on catalog objects.

The API does not support retrieving privileges granted on Arctic catalog sources.

Method and URL

GET /v0/projects/{project-id}/catalog/{id}/grants

Parameters

project-id Path   String (UUID)

Unique identifier of the project that contains the catalog object whose grants you want to retrieve.

Example: 601a5d10-5fa6-4963-a2a9-157a137558e5

---

id Path   String (UUID)

Unique identifier of the object whose grants you want to retrieve.

Example: 7f1c4660-cd7b-40d0-97d1-b8a6f431cbda

Example Request

curl -X GET 'https://api.dremio.cloud/v0/projects/601a5d10-5fa6-4963-a2a9-157a137558e5/catalog/7f1c4660-cd7b-40d0-97d1-b8a6f431cbda/grants' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Example Response

{
  "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
  "availablePrivileges": [
    "ALTER",
    "DELETE",
    "INSERT",
    "MANAGE_GRANTS",
    "SELECT",
    "TRUNCATE",
    "UPDATE"
  ],
  "grants": [
    {
      "privileges": [
        "ALTER",
        "SELECT",
        "MANAGE_GRANTS"
      ],
      "granteeType": "USER",
      "id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0",
      "name": "jeansmith",
      "firstName": "Jean",
      "lastName": "Smith",
      "email": "jean_smith@example.com"
    },
    {
      "privileges": [
        "ALTER",
        "SELECT"
      ],
      "granteeType": "ROLE",
      "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
      "name": "examplerole"
    }
  ]
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

404   Not Found