---
title: "Create or update a grant"
method: POST
path: "/v2/grants"
tags: ["Grants"]
---

# Create or update a grant

`POST /v2/grants`

## Request

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

Create a grant or update an existing grant on a document, folder, or workspace to a user or a team by ID.

  ### Usage notes
  - This endpoint can only be used to escalate the level of access that a user has to a document. To remove or reduce a user's access to a specific document, call [/v2/grants/{grantId}](https://help.sigmacomputing.com/reference/delete-grant) to delete the existing grant and re-grant the desired level of access.
  - 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.
  - Retrieve the **inodeId** by calling the [/v2/files](https://help.sigmacomputing.com/reference/list-files) endpoint and using the `id` included in the response.
  - Retrieve the **inodeId** for a data model by calling the [/v2/dataModels](https://help.sigmacomputing.com/reference/list-data-models) endpoint and using the `dataModelId` included in the response.
  - Optionally specify a **tagId** to associate the permission with a specific version tag of a workbook, dataset (deprecated), or database table. Retrieve the **tagId** by calling the [/v2/tags](https://help.sigmacomputing.com/reference/list-version-tag) endpoint and using the `versionTagId` included in the response.

## Request body

- object
  - `grantee` union, required
    - V2GrantsPostRequestBodyContentApplicationJsonSchemaGrantee0: User or member ID
      - `memberId` string, required
    - V2GrantsPostRequestBodyContentApplicationJsonSchemaGrantee1: Team ID
      - `teamId` string, required
  - `permission` union, required
    - 'admin' | 'annotate' | 'update' | 'usage' | 'writeback': Valid inode types: table, connection database, and connection schema.
    - 'create' | 'annotate' | 'organize' | 'explore' | 'view' | 'edit' | 'apply': Valid inode types: folder, workspace, workbook, dataset, and data model. Can Contribute permissions are listed as **organize** and Can Manage permissions are listed as **edit**.
    - 'view' | 'edit' | 'apply': Valid inode types: version tag.
  - `inodeId` string, required
  - `tagId` string

## Response `200`

The response body.

- GrantsCreateGrantResponse200
  - `grantId` string, required: The unique identifier of the grant
  - `inodeId` string, required: The unique identifier of the inode
  - `organizationId` string, required: The unique identifier of the organization
  - `memberId` string, nullable, required: The unique identifier of the member
  - `teamId` string, nullable, required: The unique identifier of the team
  - `permission` union, required: The permission granted to the member
    - 'admin' | 'annotate' | 'update' | 'usage' | 'writeback': Valid inode types: table, connection database, and connection schema.
    - 'create' | 'annotate' | 'organize' | 'explore' | 'view' | 'edit' | 'apply': Valid inode types: folder, workspace, workbook, dataset, and data model. Can Contribute permissions are listed as **organize** and Can Manage permissions are listed as **edit**.
    - 'view' | 'edit' | 'apply': Valid inode types: version tag.
  - `createdBy` string, required: The identifier of the user who created this grant
  - `updatedBy` string, required: The identifier of the user or process that last updated this grant
  - `createdAt` string, date-time, required: When the grant was created
  - `updatedAt` string, date-time, required: When the grant was last updated
  - `inodeType` 'folder' | 'customFunction' | 'symlink' | 'versionTag' | 'worksheet' | 'block' | 'dashboard' | 'report' | 'table' | 'semanticView' | 'metricView' | 'scope' | 'sql' | 'workbook' | 'template' | 'dataset' | 'datafile' | 'storedProcedure' | 'apiConnector' | 'apiConnectorAuth' | 'mcpConnector' | 'warehouseAgent' | 'agentSkill' | 'tlsProfile' | 'schedule' | 'application' | 'appBranch', required

---

[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)