---
title: "Grant permissions on a workbook to users or teams"
method: POST
path: "/v2/workbooks/{workbookId}/grants"
tags: ["Workbooks"]
---

# Grant permissions on a workbook to users or teams

`POST /v2/workbooks/{workbookId}/grants`

## Request

- Base URL: `https://api.sigmacomputing.com`
- URL: `https://api.sigmacomputing.com/v2/workbooks/{workbookId}/grants`
- Auth: HTTP bearer

You can use this endpoint to grant specific document permissions on a specific workbook to users or teams.

   ### Usage notes

   - Ensure the **workbookId** in the path is valid and that the user has rights to modify its permissions. Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint.
   - Do not set both **memberId** and **teamId** in the same **grantee** object. Instead, choose one based on the target of the grant.

     - Retrieve the **memberId** by calling the [/v2/members](https://help.sigmacomputing.com/reference/list-members) endpoint.
     - Retrieve the **teamId** by calling the [/v2/teams](https://help.sigmacomputing.com/reference/list-teams) endpoint.
   - Grant permissions on a specific version tag of a workbook by specifying the **tagId**. Retrieve the **tagId** by calling the [/v2/tags](https://help.sigmacomputing.com/reference/list-version-tag) endpoint and using the `versionTagId` in the response.

   ### Usage scenarios

   - **Team collaboration**: Granting edit permissions to a team for collaborative work on a project.
   - **External consultant**: Providing view access to an external consultant.

   ### Best practices

   - Validate user and team IDs before submitting them in a request to avoid errors.
   - Use the **tagId** to help manage and revoke grants systematically as project requirements change.

## Path parameters

- `workbookId` string, required

## Request body

- object
  - `grants` V2WorkbooksWorkbookIdGrantsPostRequestBodyContentApplicationJsonSchemaGrantsItems[], required
    - `grantee` union, required
      - V2WorkbooksWorkbookIdGrantsPostRequestBodyContentApplicationJsonSchemaGrantsItemsGrantee0: The UUID of the member receiving the grant
        - `memberId` string, required
      - V2WorkbooksWorkbookIdGrantsPostRequestBodyContentApplicationJsonSchemaGrantsItemsGrantee1: The UUID of the team receiving the grant
        - `teamId` string, required
    - `permission` 'view' | 'explore' | 'edit', required: Permission to grant for access to the workbook.
    - `tagId` string

## Response `200`

The response body.

- WorkbooksCreateWorkbookGrantResponse200

---

[API](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api.md) - [All operations](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/revisions/fb6036208c49?raw)