Workspace Grants API
The following article relates to Sigma’s developer API for workspace grants.
Summary of Content
Endpoints
The Grant Object
Attributes
The Grant List Object
Attributes
List Existing Workspace Grants
Grant a Member or Team Access to a Workspace
Revoke Granted Access
Related Resources
Endpoints
GET /v2/workspaces/{workspaceId}/grants
Returns a list of grants associated with the requested workspace.
Try it in Swagger
POST /v2/workspaces/{workspaceId}/grants
Creates and/or updates a workspace's grants. Returns an empty object.
Try it in Swagger
DELETE /v2/workspaces/{workspaceId}/grants/{grantId}
Revokes an existing grant. Returns an empty object.
Try it in Swagger
The Grant Object
Attributes
grantId string
The unique identifier associated with the grant.
organizationId string
The unique identifier associated with the Sigma organization in which the workspace lives.
memberId string | null
The unique identifier associated with the organization member assigned to the grant.
If the grant is specific to a team, not an individual member, this value will be null.
teamId string | null
The unique identifier associated with the team assigned to the grant.
If the grant is specific to an organization member, not a team, this value will be null.
permission string
The permission type associated with the grant.
See Data permissions.
These are the permissions, and the labels that display them in Sigma UI:
- edit
- Can Manage
- organize
- Can Contribute
- explore
- Can Explore
- view
- Can View
createdBy string
The unique identifier, memberId, of the organization member who created the grant.
updatedBy string
The unique identifier, memberId, of the organization member who created the grant.
createdAt string
The timestamp at which the grant was created.
updatedAt string
The timestamp at which the grant was last updated.
{
"grantId":"qt2de26e-9a2c-4f45-ba1c-91a0875df8ez",
"organizationId":"cf2de26e-9a2c-4c58-ba1c-91a0955df7ez",
"memberId": "D09b2ZDXwvssbKuMZRWUdk0c6h892",
"teamId": null,
"permission": "organize",
"createdBy":"6VZszXPJqLXpIezceRadESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
"createdAt": "2022-02-28T21:42:56.809Z",
"updatedAt": "2022-03-28T21:12:56.108Z"
}
The Grant List Object
Attributes
entries Array<Grant Object>
A list of grant objects matching the requested workspaceId and parameters.
hasMore boolean
True if additional grants are available for the requested workspace.
nextPage string | null
The next page in the list of grants. Used for pagination.
List Existing Workspace Grants
Returns a list grants associated with the requested workspace.
GET /v2/workspaces/{workspaceId}/grants
Permissions
-
The user account associated with the API access token will only see grants to workspaces they have permission to manage.
Note: If you encounter a permission error for the given endpoint, verify your account type and permissions associated with your API token.
Parameters
page string [optional]
An identifier used for pagination.
limit number [optional]
The number of materialization entries to be returned.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/workspaces/{workspaceId}/grants?page={page}&limit={limit} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns a grant list object.
{
"entries": [
{
"grantId": string,
"organizationId": string,
"memberId": string | null,
"teamId": string | null,
"permission": string,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string
}
],
"hasMore": boolean,
"nextPage": string | null
}
Example
Example Request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/workspaces/g3e8e8947-c9f5-43re-93b0-T80d0ddf5627/grants?page={3}&limit={4} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{
"entries": [
{
"grantId":"qt2de26e-9a2c-4f45-ba1c-91a0875df8ez",
"organizationId":"cf2de26e-9a2c-4c58-ba1c-91a0955df7ez",
"memberId": "D09b2ZDXwvssbKuMZRWUdk0c6h892",
"teamId": null,
"permission": "organize",
"createdBy":"6VZszXPJqLXpIezceRadESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
"createdAt": "2022-02-28T21:42:56.809Z",
"updatedAt": "2022-03-28T21:12:56.108Z"
}
],
"hasMore": true,
"nextPage": "2"
}
Grant a Member or Team Access to a Workspace
Creates and/or updates a workspace's grants. Returns an empty object.
Note: No more than a total of 100 can be added or removed at a time.
POST /v2/workspaces/{workspaceId}/grants
Permissions
-
The user account associated with the API access token must have permission to manage workspace permissions.
Note: If you encounter a permission error for the given endpoint, verify your account type and permissions associated with your API token.
Parameters
grants Array<{grantee, permission}>
A list of one or more objects describing the grant(s) to be added.
Example — Single Grant
{
grantee: { memberId: string } | { teamId: string }
permission: string // 'edit', 'organize', 'explore', 'view'
}
Example — List of Grants
[
{
grantee: {
memberId: "6VZszXPJqLXpIezcD5adESnwfPPUg"
},
permission: "explore"
},
{
grantee: {
teamId: "88858466-5299-4425-95c0-4b7d93268bae"
},
permission: "edit"
}
]
cURL Request
curl --location --request POST 'https://api.sigmacomputing.com/v2/workspace/{workspaceId}/grants' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{"grants": [
{
grantee: { memberId: string } | { teamId: string }
permission: string // 'edit', 'organize', 'explore', 'view'
},
...
]}'
Response
{}
Example
Example Request:
curl --location --request POST 'https://api.sigmacomputing.com/v2/workspace/g3e8e8947-c9f5-43re-93b0-T80d0ddf5627/grants' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{"grants": [
{
grantee: {
memberId: "6VZszXPJqLXpIezcD5adESnwfPPUg"
},
permission: "explore"
},
{
grantee: {
teamId: "88858466-5299-4425-95c0-4b7d93268bae"
},
permission: "edit"
}
]}'
Example Response:
{}
Revoke Granted Access
Revokes an existing grant. Returns an empty object.
DELETE /v2/workspaces/{workspaceId}/grants/{grantId}
Permissions
-
The user account associated with the API access token must have permission to manage workspace permissions.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
None
cURL Request
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/workspaces/{workspaceId}/grants/{grantId} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{}
Example
Example Request:
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/workspaces/g3e8e8947-c9f5-43re-93b0-T80d0ddf5627/grants/qt2de26e-9a2c-4f45-ba1c-91a0875df8ez \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{}
Related Resources
API Documentation
Get an API Token and Client Id
Identify Unique Ids in Sigma