Grants

Use the Catalog API to grant privileges to users and roles and retrieve lists of the privileges that are available on specific catalog objects.

Grants Object (Non-Arctic Catalog Source)

{
  "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
  "availablePrivileges": [
    "ALTER",
    "ALTER_REFLECTION",
    "CREATE_TABLE",
    "DELETE",
    "DROP",
    "INSERT",
    "MANAGE_GRANTS",
    "MODIFY",
    "READ_METADATA",
    "SELECT",
    "TRUNCATE",
    "UPDATE",
    "VIEW_REFLECTION"
  ],
  "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 Object (Arctic Catalog Source)

{
  "id": "4143a215-4990-4a3c-9cb6-cd714bcd97a2",
  "availablePrivileges": [
    "ALTER_REFLECTION",
    "COMMIT",
    "CREATE_BRANCH",
    "CREATE_FOLDER",
    "CREATE_TABLE",
    "CREATE_TAG",
    "CREATE_VIEW",
    "MANAGE_GRANTS",
    "MODIFY",
    "SELECT",
    "USAGE",
    "VIEW_REFLECTION",
    "WRITE"
  ],
  "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"
    }
  ],
  "tag": "8e62afbc-7f18-42fa-b5a4-69d97d3c997a"
}

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"}]

tag String (UUID)

For Arctic catalog sources, the unique identifier for the instance of the source. Dremio changes this tag whenever a change is made to the source. Immutable by the user. Not included for objects that are not Arctic catalog sources.

Example: 8e62afbc-7f18-42fa-b5a4-69d97d3c997a

Attributes of Objects in the `grants` Array

privileges Array of String

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

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.

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. If you omit the users or roles object or a specific user or role in a PUT request, Dremio removes all existing explicit access settings for the omitted object, user, or role. To keep existing access settings, duplicate the existing users and roles objects in the PUT request and add other updates.

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"}]

tag String (UUID)

For Arctic catalog sources, the unique identifier for the instance of the source. Dremio changes the tag whenever the Arctic catalog source changes and uses the tag value to ensure that PUT requests apply to the most recent version of the source. Required only for requests to create or update grants on an Arctic catalog sources.

Get the tag from the response for a request to retrieve privileges and grantees for an Arctic catalog source.

Example: 8e62afbc-7f18-42fa-b5a4-69d97d3c997a

Parameters of Objects in the `grants` Array

privileges Body Array of String

List of privileges to grant to the user or role. 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 (Non-Arctic Catalog Source)

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 Request (Arctic Catalog Source)

curl -X PUT 'https://api.dremio.cloud/v0/projects/601a5d10-5fa6-4963-a2a9-157a137558e5/catalog/4143a215-4990-4a3c-9cb6-cd714bcd97a2/grants' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grants": [
    {
      "privileges": [
        "SELECT",
        "USAGE",
        "VIEW_REFLECTION"
      ],
      "granteeType": "USER",
      "id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0"
    },
    {
      "privileges": [
        "ALTER_REFLECTION",
        "COMMIT",
        "CREATE_BRANCH",
        "CREATE_FOLDER",
        "CREATE_TABLE",
        "CREATE_TAG",
        "CREATE_VIEW",
        "MODIFY",
        "SELECT",
        "USAGE",
        "VIEW_REFLECTION",
        "WRITE"
      ],
      "granteeType": "ROLE",
      "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889"
    }
  ],
  "tag": "8e62afbc-7f18-42fa-b5a4-69d97d3c997a"
}'

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 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 (Non-Arctic Catalog Source)

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 (Non-Arctic Catalog Source)

{
  "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
  "availablePrivileges": [
    "ALTER",
    "ALTER_REFLECTION",
    "CREATE_TABLE",
    "DELETE",
    "DROP",
    "INSERT",
    "MANAGE_GRANTS",
    "MODIFY",
    "READ_METADATA",
    "SELECT",
    "TRUNCATE",
    "UPDATE",
    "VIEW_REFLECTION"
  ],
  "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"
    }
  ]
}

Example Request (Arctic Catalog Source)

curl -X GET 'https://api.dremio.cloud/v0/projects/601a5d10-5fa6-4963-a2a9-157a137558e5/catalog/4143a215-4990-4a3c-9cb6-cd714bcd97a2/grants' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Example Response (Arctic Catalog Source)

{
  "id": "4143a215-4990-4a3c-9cb6-cd714bcd97a2",
  "availablePrivileges": [
    "ALTER_REFLECTION",
    "COMMIT",
    "CREATE_BRANCH",
    "CREATE_FOLDER",
    "CREATE_TABLE",
    "CREATE_TAG",
    "CREATE_VIEW",
    "MANAGE_GRANTS",
    "MODIFY",
    "SELECT",
    "USAGE",
    "VIEW_REFLECTION",
    "WRITE"
  ],
  "grants": [
    {
      "privileges": [
        "SELECT",
        "USAGE",
        "VIEW_REFLECTION"
      ],
      "granteeType": "USER",
      "id": "27937a63-e7e5-4478-8d3c-4ad3f20d43c0",
      "name": "jeansmith",
      "firstName": "Jean",
      "lastName": "Smith",
      "email": "jean_smith@example.com"
    },
    {
      "privileges": [
        "ALTER_REFLECTION",
        "COMMIT",
        "CREATE_BRANCH",
        "CREATE_FOLDER",
        "CREATE_TABLE",
        "CREATE_TAG",
        "CREATE_VIEW",
        "MODIFY",
        "SELECT",
        "USAGE",
        "VIEW_REFLECTION",
        "WRITE"
      ],
      "granteeType": "ROLE",
      "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
      "name": "examplerole"
    }
  ],
  "tag": "9f3e9a5f-dcfe-4925-8632-e42659dbf225"
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Grants Attributes​

Attributes of Objects in the grants Array​

Creating or Updating Grants on a Catalog Object​

Parameters​

Parameters of Objects in the grants Array​

Response Status Codes​

Retrieving Privileges and Grantees on a Catalog Object​

Parameters​

Response Status Codes​

Grants Attributes

Attributes of Objects in the `grants` Array

Creating or Updating Grants on a Catalog Object

Parameters

Parameters of Objects in the `grants` Array

Response Status Codes

Retrieving Privileges and Grantees on a Catalog Object

Parameters

Response Status Codes