Grants Enterprise

Use the Catalog API to grant user and role privileges on specific catalog objects.

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.

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.

note

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 Objects in the grants Array

privileges String

List of privileges granted to the user or role. For more information, 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

For users, the user's first name. Not included for roles.

Example: Jean

---

lastName String

For users, the user's last name. Not included for roles.

Example: Smith

---

email String

For users, the user's email address. Not included for roles.

Example: jean_smith@example.com

Creating or Updating Privilege 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 privilege grants on catalog objects.

Method and URL

PUT /api/v3/catalog/{id}/grants

Parameters

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 each user's and role's specific privileges. 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 Objects in the grants Array

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. For more information, read Privileges.

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://{hostname}/api/v3/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

403   Forbidden

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

Use this endpoint in place of the Catalog API Privileges endpoint, which is deprecated. We expect to remove the Privileges endpoint by July 2025.

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

Method and URL

GET /api/v3/catalog/{id}/grants

Parameters

id Path   String (UUID)

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

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

Example Request

curl -X GET 'https://{hostname}/api/v3/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

403   Forbidden

404   Not Found