Create a direct share in Dynatrace with the Document API, assigning read or read-write access to selected users or groups for a document you can share.
| POST | SaaS | https://{your-environment-id}.apps.dynatrace.com/platform/document/v1/direct-shares |
Create a direct-share for a document. This is only possible for documents you own, as well as for reshareable documents owned by other users to which you have write access. The share can be used to grant access to a specific set of users and/or groups, via addRecipients.
You can optionally add users and/or groups which will directly be registered as recipients of the share. The users and groups are specified via their sso-ids. The maximum number of recipients is 1000.
The validity of the SSO-users and SSO-groups isn't verified. It's technically possible, albeit pointless, to add non-existing users and groups.
The share can be created with either read or read-write access.
A document can have maximally one direct-share per access type, therefore it's impossible to create multiple read-shares or multiple read-write-shares for a single document.
This means, that you can create one read-share for a document, and this single read-share can be used to give read-access to an arbitrary number of users (and/or groups). The same applies to a read-write-share.
To execute this request, you need a platform token or OAuth access token with document:direct-shares:write scope. To learn how to obtain and use it, see Tokens and authentication.
| Parameter | Type | Description | In | Required |
|---|---|---|---|---|
| send-notification | boolean | Indicates whether a notification shall be sent to share recipients or new document owners. Notifications are only sent for documents whose type is supported by at least one app installed in the environment. | query | Optional |
| body | Create | Input required to create a direct-share. | body | Required |
CreateDirectShare objectInput required to create a direct-share.
| Element | Type | Description | Required |
|---|---|---|---|
| documentId | string | Document id. | Required |
| access | string | Specifies which permissions shall be granted via the share: - | Required |
| recipients | Sso | An array of sso-users (sso-ids). These users will immediately get access to the document. Can be empty. | Required |
SsoEntity objectA SSO user or SSO group.
| Element | Type | Description | Required |
|---|---|---|---|
| id | string | SSO id of a user or group. | Required |
| type | string | Type of the SSO entity - either | Required |
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{"documentId": "string","access": "string","recipients": [{"id": "441664f0-23c9-40ef-b344-18c02c23d789","type": "group"}]}
| Code | Type | Description |
|---|---|---|
| 201 | Direct | A new share for the specified document has been created. |
| 400 | - | - |
| 401 | - | - |
| 403 | - | - |
| 404 | - | - |
| 409 | - | - |
| 500 | - | - |
| 503 | - | - |
| default | - | - |
DirectShare object| Element | Type | Description |
|---|---|---|
| id | string | System-generated id. |
| documentId | string | The shared document's id. |
| access | string[] | The access granted by this share. |
| userCount | integer | Number of users who have been directly assigned to this share and therefore can access the document and collaborate on it. Not that potentially assigned groups and their users (see groupCount) are not reflected in this number. |
| groupCount | integer | Number of groups which have been assigned to this share. |
{"id": "af21cc73-bb1c-45f1-ad1b-12e8f91b9fbc","documentId": "1d1cf013-fd4c-463e-a8ad-912485daf711","access": ["read","write"],"userCount": 2,"groupCount": 1}