Try it free

Create a direct share

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026

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.

POSTSaaShttps://{your-environment-id}.apps.dynatrace.com/platform/document/v1/direct-shares

Overview

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.

Authentication

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.

Parameters

ParameterTypeDescriptionInRequired
send-notificationboolean

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.

queryOptional
bodyCreateDirectShare

Input required to create a direct-share.

bodyRequired

Request body objects

The CreateDirectShare object

Input required to create a direct-share.

ElementTypeDescriptionRequired
documentIdstring

Document id.

Required
accessstring

Specifies which permissions shall be granted via the share: - read - grants permission to read the document, but not to update or delete it. - read-write - grants permission to read and update the document, but not to delete it.

Required
recipientsSsoEntity[]

An array of sso-users (sso-ids). These users will immediately get access to the document. Can be empty.

Required

The SsoEntity object

A SSO user or SSO group.

ElementTypeDescriptionRequired
idstring

SSO id of a user or group.

Required
typestring

Type of the SSO entity - either user or group.

Required

Request body JSON model

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"
}
]
}

Response

Response codes

CodeTypeDescription
201DirectShare

A new share for the specified document has been created.

400--
401--
403--
404--
409--
500--
503--
default--

Response body objects

The DirectShare object

ElementTypeDescription
idstring

System-generated id.

documentIdstring

The shared document's id.

accessstring[]

The access granted by this share.

userCountinteger

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.

groupCountinteger

Number of groups which have been assigned to this share.

Response body JSON models

{
"id": "af21cc73-bb1c-45f1-ad1b-12e8f91b9fbc",
"documentId": "1d1cf013-fd4c-463e-a8ad-912485daf711",
"access": [
"read",
"write"
],
"userCount": 2,
"groupCount": 1
}
Related tags
Platform APIDynatrace Platform