Document permission APIs
The document permission APIs allow you to manage the permissions of documents in Omni. To create and manage documents, use the Document APIs.
Document permission object
Represents a document permission in Omni.
- Example
- Fields
{
"description": "Organization",
"direct": {
"accessBoost": false,
"isOwner": false,
"role": "VIEWER"
},
"id": "df290ed4-b721-4efe-914b-95d30ce1c5f2",
"name": "Organization",
"type": "user"
}
Add document permissions
Grants document permissions to users or user groups.
curl -L -X POST 'https://myorg.omniapp.co/api/v1/documents/12db1a0a/permissions' \
-H 'Authentication: Bearer <TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"role": "VIEWER",
"accessBoost": false,
"userIds": ["f4df8d6e-7f69-4d54-b23b-7abfe5c4da74"]
}'
Parameters
Response
200 OK
Successful requests will return a 200 OK status and a response body similar to the following:
{
"success": true
}
400 Bad Request
Response bodies will be an object similar to the following:
{
"detail": "<errorReason>",
"status": 400
}
| Issue | Error detail |
|---|---|
Missing userId or userGroupIds parameter | userIds.userGroupIds: userIds or userGroupIds must be provided |
Invalid userId value | userIds.0: Invalid uuid |
Invalid userGroupIds value | userGroupIds.0: Invalid uuid |
403 Forbidden
Response bodies will be an object similar to the following:
{
"detail": "User does not have permission to manage document permissions",
"status": 403
}
The user sending the API request must have Manager permissions for the document.
404 Not Found
{
"detail": "Document with identifier \"<documentId>\" not found",
"status": 404
}
429 Too Many Requests
Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.
Update document permissions
Updates existing document permissions for users or user groups.
curl -L -X PATCH 'https://myorg.omniapp.co/api/v1/documents/12db1a0a/permissions' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"role": "VIEWER",
"accessBoost": false,
"userIds": ["f4df8d6e-7f69-4d54-b23b-7abfe5c4da74"]
}'
Parameters
Response
200 OK
Successful requests will return a 200 OK status and a response body similar to the following:
{
"success": true
}
400 Bad Request
Response bodies will be an object similar to the following:
{
"detail": "<errorReason>",
"status": 400
}
| Issue | Error detail |
|---|---|
Missing userId or userGroupIds parameter | userIds.userGroupIds: userIds or userGroupIds must be provided |
Invalid userId value | userIds.0: Invalid uuid |
Invalid userGroupIds value | userGroupIds.0: Invalid uuid |
403 Forbidden
Response bodies will be an object similar to the following:
{
"detail": "User does not have permission to manage document permissions",
"status": 403
}
The user sending the API request must have Manager permissions for the document.
404 Not Found
{
"detail": "Document with identifier \"<documentId>\" not found",
"status": 404
}
429 Too Many Requests
Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.
Update document permission settings
Updates the permission and interactivity settings for a document. For example, the ability to allow users to schedule or download the document's content.
curl -L -X PUT 'https://myorg.omniapp.co/api/v1/documents/12db1a0a/permissions' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"organizationRole": "VIEWER",
"organizationAccessBoost": false,
"canDownload": true,
"canDrill": true,
"canSchedule": true,
"canUpload": true,
"canViewWorkbook": true
}'
Parameters
Response
200 OK
Successful requests will return a 200 OK status and a response body similar to the following:
{
"success": true
}
400 Bad Request
Response bodies will be an object similar to the following:
{
"detail": "<errorReason>",
"status": 400
}
| Issue | Error detail |
|---|---|
| Invalid parameter value | <parameter>: Invalid <parameter> |
403 Forbidden
Response bodies will be an object similar to the following:
{
"detail": "User does not have permission to manage document permissions",
"status": 403
}
The user sending the API request must have Manager permissions for the document.
404 Not Found
{
"detail": "Document with identifier \"<documentId>\" not found",
"status": 404
}
429 Too Many Requests
Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.
Retrieve document permissions for a user
curl -L 'https://myorg.omniapp.co/api/v1/documents/12db1a0a/permissions' \
-H 'Authentication: Bearer <TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"userId": "f4df8d6e-7f69-4d54-b23b-7abfe5c4da74"
}'
Parameters
Response
200 OK
Successful requests will return a 200 OK status and a response body similar to the following:
{
"success": true
}
400 Bad Request
Response bodies will be an object similar to the following:
{
"detail": "<errorReason>",
"status": 400
}
| Issue | Error detail |
|---|---|
Missing userId parameter | userId: userId must be provided |
Invalid userId value | userId: Invalid userId |
403 Forbidden
Response bodies will be an object similar to the following:
{
"detail": "User does not have permission to manage document permissions",
"status": 403
}
The user sending the API request must have Manager permissions for the document.
404 Not Found
{
"detail": "Document with identifier \"<documentId>\" not found",
"status": 404
}
429 Too Many Requests
Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.
Revoke document permissions
curl -L -X DELETE 'https://myorg.omniapp.co/api/v1/documents/12db1a0a/permissions' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"userIds": ["f4df8d6e-7f69-4d54-b23b-7abfe5c4da74"]
}'
Parameters
Response
200 OK
Successful requests will return a 200 OK status and a response body similar to the following:
{
"success": true
}
400 Bad Request
Response bodies will be an object similar to the following:
{
"detail": "<errorReason>",
"status": 400
}
| Issue | Error detail |
|---|---|
Missing userId parameter | userId: userId must be provided |
Invalid userId value | userId: Invalid userId |
403 Forbidden
Response bodies will be an object similar to the following:
{
"detail": "User does not have permission to manage document permissions",
"status": 403
}
The user sending the API request must have Manager permissions for the document.
404 Not Found
{
"detail": "Document with identifier \"<documentId>\" not found",
"status": 404
}
429 Too Many Requests
Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.