DRACOON API
REST Web Services for DRACOON
This page provides an overview of all available and documented DRACOON APIs, which are grouped by tags.
Each tag provides a collection of APIs that are intended for a specific area of the DRACOON.
- Homepage
- https://api.apis.guru/v2/specs/dracoon.team/4.42.2.json
- Provider
- dracoon.team
- OpenAPI version
- 3.0.1
- Spec (JSON)
- https://api.apis.guru/v2/specs/dracoon.team/4.42.2/openapi.json
- Spec (YAML)
- https://api.apis.guru/v2/specs/dracoon.team/4.42.2/openapi.yaml
Tools (299)
Extracted live via the executor SDK.
-
auth.completeOpenIdLogin🚧 Deprecated since v4.14.0
Description:
This is the second step of the OpenID Connect authentication.
The user hands over the authorization code and is logged in.Precondition:
Existing user with activated OpenID Connect authentication that is NOT locked.
Postcondition:
User is logged in.
Further Information:
None.
-
auth.initiateOpenIdLogin🚧 Deprecated since v4.14.0
Description:
This is the first step of the OpenID Connect authentication.
The user is send to the OpenID Connect identity provider to authenticate himself and retrieve an authorization code.Precondition:
None.
Postcondition:
User is redirected to OpenID Connect identity provider to authenticate himself.
Further Information:
None.
-
auth.login🚧 Deprecated since v4.13.0
Description:
Authenticates user and provides an authentication token (
X-Sds-Auth-Token) that is required for the most operations.Precondition:
Existing user that is NOT locked.
Postcondition:
User is logged in.
Further Information:
The provided token is valid for two hours, every usage resets this period to two full hours again.
Logging off invalidates the token.Available authentication methods:
Expand
-
auth.pingDescription:
Test connection to DRACOON Core Service.
Precondition:
None.
Postcondition:
200 OKwith current date string is returned if successful.Further Information:
None.
-
auth.recoverUserName🚀 Since v4.13.0
Description:
Request an email with the user names of all accounts connected to the email.
Precondition:
Valid email address.
Postcondition:
An email is sent to the provided address, with a list of account user names connected to it.
Further Information:
None.
-
auth.requestPasswordResetDescription:
Request an email with a password reset token for a certain user to reset password.
Precondition:
Registered user account.
Postcondition:
Provided user receives email with password reset token.
Further Information:
None.
-
auth.resetPasswordDescription:
Resets user's password.
Precondition:
User received a password reset token.
Postcondition:
User's password is reset to the provided password.
Further Information:
Forbidden characters in passwords: [
&,',<,>] -
auth.validateResetPasswordTokenDescription:
Request all information for a password change dialogue e.g. real name of user.
Precondition:
User received a password reset token.
Postcondition:
Context information is returned.
Further Information:
None.
-
config.requestAlgorithms🚀 Since v4.24.0
Description:
Retrieve a list of available algorithms used for encryption.
Precondition:
Authenticated user.
Postcondition:
List of available algorithms is returned.
Further Information:
None.
-
config.requestClassificationPoliciesConfigInfo🚀 Since v4.30.0
Description:
Retrieve a list of classification policies:
shareClassificationPolicies
Precondition:
Authenticated user.
Postcondition:
List of configured classification policies is returned.
Further Information:
classificationRequiresSharePassword: When a node has this classification or higher, it cannot be shared without a password. If the node is an encrypted file this policy has no effect.0means no password will be enforced. -
config.requestCurrentProductPackages🚀 Since v4.38.0
Description:
Returns a list of currently enabled product packages.
Precondition:
Authenticated user
Postcondition:
List of currently enabled Product Packages is returned.
Further Information:
-
config.requestGeneralSettingsInfo🚀 Since v4.6.0
Description:
Returns a list of configurable general settings.
Precondition:
Authenticated user.
Postcondition:
List of configurable general settings is returned.
Further Information:
None.
Configurable general settings:
Expand
Deprecated general settings:
Expand
-
config.requestGuestUsersPoliciesConfigInfo🚀 Since v4.40.0
Description:
Retrieve a list of guest users policies.
Precondition:
Authenticated user.
Postcondition:
List of configured guest users policies is returned.
Further Information:
None.
-
config.requestInfrastructurePropertiesInfo🚀 Since v4.6.0
Description:
Returns a list of read-only infrastructure properties.
Precondition:
Authenticated user.
Postcondition:
List of infrastructure properties is returned.
Further Information:
Source:
core-service.propertiesRead-only infrastructure properties:
Expand
-
config.requestNotificationChannelsInfo🚀 Since v4.20.0
Description:
Retrieve a list of configured notification channels.
Precondition:
Authenticated user.
Postcondition:
List of notification channels is returned.
Further Information:
None.
-
config.requestPasswordPoliciesConfigInfo🚀 Since v4.14.0
Description:
Retrieve a list of configured password policies for all password types:
loginsharesencryption
Precondition:
Authenticated user.
Postcondition:
List of configured password policies is returned.
Further Information:
None.
Available password policies:
Expand
-
config.requestProductPackages🚀 Since v4.38.0
Description:
Returns a list of product packages.
Precondition:
Authenticated user
Postcondition:
List of Product Packages is returned.
Further Information:
-
config.requestS3TagsInfo🚀 Since v4.9.0
Description:
Retrieve all configured S3 tags.
Precondition:
Authenticated user.
Postcondition:
List of configured S3 tags is returned.
Further Information:
An empty list is returned if no S3 tags are found / configured.
-
config.requestSystemDefaultsInfo🚀 Since v4.6.0
Description:
Returns a list of configurable system default values.
Precondition:
Authenticated user.
Postcondition:
List of configurable default settings is returned.
Further Information:
None.
Configurable default values:
Expand
-
config.requestSystemSettings🚧 Deprecated since v4.6.0
Description:
Returns a list of configurable system settings.
Precondition:
Right 🔓 read global config required.
Postcondition:
List of configurable settings is returned.
Further Information:
Check for every settings key new corresponding API and key below.
If
eula_activeis true, but NOT accepted yet, or password MUST be changed, only the following two values are returned:allow_system_global_weak_passwordeula_active
Configurable settings
Expand
Deprecated settings
Expand
-
config.updateSystemSettings🚧 Deprecated since v4.6.0
Description:
Update configurable settings.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
One or more global settings gets changed.
Further Information:
This API is deprecated and will be removed in the future.
Check for every settings key new corresponding API and key below.Configurable settings:
Expand
Deprecated settings:
Expand
-
downloads.downloadAvatar🚀 Since v4.11.0
Description:
Download avatar for given user ID and UUID.
Precondition:
Valid UUID.
Postcondition:
Stream is returned.
Further Information:
None.
-
downloads.downloadFileViaTokenDescription:
Download a file.
Precondition:
Valid download token.
Postcondition:
Stream is returned.
Further Information:
Range requests are supported.
-
downloads.downloadFileViaToken1Description:
Download a file.
Precondition:
Valid download token.
Postcondition:
Stream is returned.
Further Information:
Range requests are supported.
-
downloads.downloadZipArchiveViaTokenDescription:
Download multiple files in a ZIP archive.
Precondition:
Valid download token.
Postcondition:
Stream is returned.
Further Information:
Create a download token with
POST /nodes/zipAPI. -
eventlog.requestAuditNodeInfo🚀 Since v4.31.0
Description:
Retrieve a list of all nodes of type room under a certain parent.
Precondition:
Right 🔓 read audit log required.
Postcondition:
List of rooms.
Further Information:
For rooms on root level, use parent_id = 0.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
nodeName:cn:searchString_1|nodeIsEncrypted:eq:true
Filter by node name containingsearchString_1AND node is encrypted .Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
nodeName:asc
Sort bynodeNameascending.Sorting options:
Expand
-
eventlog.requestAuditNodeUserData🚧 Deprecated since v4.32.0
Description:
Retrieve a list of all nodes of type room, and the room assignment users with permissions.
Precondition:
Right 🔓 read audit log required.
Postcondition:
List of rooms and their assigned users is returned.
Further Information:
Output is limited to 500 entries.
For more results please use filter criteria and thelimitparameter.Filtering:
All filter fields are connected via logical conjunction (AND)
Except foruserName,userFirstNameanduserLastName- these are connected via logical disjunction (OR)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
userName:cn:searchString_1|userFirstName:cn:searchString_2|nodeId:eq:2
Filter by user login containingsearchString_1OR first name containingsearchString_2AND node ID equals2.Filtering options:
Expand
Deprecated filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
nodeName:asc
Sort bynodeNameascending.Sorting options:
Expand
-
eventlog.requestLogEventsAsJson🚀 Since v4.3.0
Description:
Retrieve eventlog (audit log) events.
Precondition:
Role 👤 Log Auditor required.
Postcondition:
List of audit log events is returned.
Further Information:
Output is limited to 500 entries.
For more results please use filter criteria and paging (offset+limit).Allowed
Accept-Header:Accept: application/jsonAccept: text/csv
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
time:desc
Sort bytimedescending (default sort option).Sorting options:
Expand
-
eventlog.requestLogOperations🚀 Since v4.3.0
Description:
Retrieve eventlog (audit log) operation IDs and the associated log operation description.
Precondition:
Role 👤 Log Auditor required.
Postcondition:
List of available log operations is returned.
Further Information:
None.
-
groups.addGroupMembersDescription:
Add members to a group.
Precondition:
Right 🔓 change groups required.
Postcondition:
New members are added to the group.
Further Information:
Batch function.
The newly provided members will be added to the existing ones. -
groups.createGroupDescription:
Create a new user group.
Precondition:
Right 🔓 change groups required.
Postcondition:
A new user group is created.
Further Information:
- If a group should NOT expire, leave
expireAtempty. - Group names are limited to 150 characters
- Forbidden characters in group name: [
<,>]
- If a group should NOT expire, leave
-
groups.removeGroupDescription:
Delete a user group.
Precondition:
Right 🔓 delete groups required.
Postcondition:
User group is deleted.
Further Information:
None.
-
groups.removeGroupMembersDescription:
Remove group members.
Precondition:
Right 🔓 change groups required.
Postcondition:
Provided users are removed from the user group.
Further Information:
Batch function.
The provided users are removed from the user group. Maximum number of users to remove in one request is 200. -
groups.requestGroupDescription:
Retrieve detailed information about a user group.
Precondition:
Right 🔓 read groups required.
Postcondition:
User group is returned.
Further Information:
None.
-
groups.requestGroupMembersDescription:
Retrieve a list of group member users or / and users who can become a member.
Precondition:
Right 🔓 read groups required.
Postcondition:
List of users is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isMember:eq:false|user:cn:searchString
Get all users that are NOT in this group AND whose (firstNameORlastNameORemailORusername) is likesearchString.Filtering options:
Expand
Deprecated filtering options:
Expand
-
groups.requestGroupRolesDescription:
Retrieve a list of all roles granted to a group.
Precondition:
Right 🔓 read groups required.
Postcondition:
List of granted roles is returned.
Further Information:
None.
-
groups.requestGroupRooms🚧 Deprecated since v4.10.0
Description:
Retrieves a list of rooms granted to the group and / or that can be granted.
Precondition:
Right 🔓 read groups required.
Postcondition:
List of rooms is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isGranted:eq:false|name:cn:searchString
Get all rooms where the group is NOT granted AND whose name is likesearchString.Filtering options:
Expand
-
groups.requestGroupsDescription:
Returns a list of user groups.
Precondition:
Right 🔓 read groups required.
Postcondition:
List of user groups is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
name:cn:searchString
Filter by group name containingsearchString.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
name:asc|expireAt:desc
Sort bynameascending AND byexpireAtdescending.Sorting options:
Expand
-
groups.requestLastAdminRoomsGroups🚀 Since v4.10.0
Description:
Retrieve a list of all rooms where the group is defined as last admin group.
Precondition:
Right 🔓 change groups required.
Postcondition:
List of rooms is returned.
Further Information:
An empty list is returned if no rooms were found where the group is defined as last admin group.
-
groups.updateGroupDescription:
Update user group's metadata .
Precondition:
Right 🔓 change groups required.
Postcondition:
User group's metadata is changed.
Further Information:
- If a group should NOT expire, leave
expireAtempty. - Group names are limited to 150 characters
- All characters are allowed.
- If a group should NOT expire, leave
-
internal.internalRequestSubscriptionPlan🚀 Since v4.36.0
Description:
Get the subscription plan id of the current tenant
Precondition:
Valid
X-SDS-Service-TokenHeaderPostcondition:
Returns SubscriptionPlanResponse model that includes subscription plan id.
Further Information:
None.
-
internal.internalSetSubscriptionPlan🚀 Since v4.36.0
Description:
Change the subscription plan id of the current tenant
Precondition:
Valid
X-SDS-Service-TokenHeaderPostcondition:
The subscription plan of the current tenant is set to the given value.
Returns SubscriptionPlanResponse model that includes subscription plan id.Further Information:
None.
-
nodes.addFavoriteDescription:
Marks a node (room, folder or file) as favorite.
Precondition:
Authenticated user is allowed to 👁 see the node (i.e.
isBrowsable = true).Postcondition:
A node gets marked as favorite.
Further Information:
None.
-
nodes.addRoomGuestUsersDescription:
Add guest users to a room
Precondition:
User needs to be a 👤 Room Administrator. To add new members, the user needs the right 🔓 non-members add, which is included in any role. 👤 Guest User Policy needs to be enabled.
Postcondition:
New or existing Guest-Users now have guest-permissions for this room
Further Information:
Batch function.
-
nodes.cancelFileUploadDescription:
Cancel a (S3) file upload and destroy the upload channel.
Precondition:
An upload channel has been created and user has to be the creator of the upload channel.
Postcondition:
The upload channel is removed and all temporary uploaded data is purged.
Further Information:
It is recommended to notify the API about cancelled uploads if possible.
-
nodes.changePendingAssignmentsDescription:
Handles a list of user-room assignments by groups that have NOT been approved yet
WAITING or DENIED assignments can be ACCEPTED.Precondition:
None.
Postcondition:
User-room assignment is approved and the user gets access to the group.
Further Information:
Room administrators should SHOULD handle pending assignments to provide access to rooms for other users.
-
nodes.completeFileUpload🚧 Deprecated since v4.9.0
Use
uploadsAPIDescription:
Finishes an upload and closes the corresponding upload channel.
Precondition:
An upload channel has been created and data has been transmitted.
Postcondition:
The upload is finished and the temporary file is moved to the productive environment.
Further Information:
The provided file name might be changed in accordance with the resolution strategy:
- autorename: changes the file name and adds a number to avoid conflicts.
- overwrite: deletes any old file with the same file name.
- fail: returns an error; in this case, another
PUTrequest with a different file name may be sent.
Please ensure that all chunks have been transferred correctly before finishing the upload.
Download share id (if exists) gets changed if:- node with the same name exists in the target container
resolutionStrategyisoverwritekeepShareLinksistrue
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.completeS3FileUpload🚀 Since v4.15.0
Description:
Finishes a S3 file upload and closes the corresponding upload channel.
Precondition:
An upload channel has been created, data has been transmitted and user has to be the creator of the upload channel
Postcondition:
Upload channel is closed. S3 multipart upload request is completed.
Further Information:
Download share id (if exists) gets changed if:
- node with the same name exists in the target container
resolutionStrategyisoverwritekeepShareLinksistrue
-
nodes.configureRoomDescription:
Configure a room.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Room's configuration is changed.
Further Information:
Provided (or default) classification is taken from room when file gets uploaded without any classification.
To set
adminIdsoradminGroupIdstheinheritPermissionsvalue has to befalse. Otherwise use:PUT /nodes/rooms/{room_id}/groupsPUT /nodes/rooms/{room_id}/users
APIs.
-
nodes.copyNodesDescription:
Copies nodes (folder, file) to another parent.
Precondition:
Authenticated user with 🔓 read permissions in the source parent and 🔓 create permissions in the target parent node.
Postcondition:
Nodes are copied to target parent.
Further Information:
Nodes MUST be in same source parent.
Rooms CANNOT be copied.Download share id (if exists) gets changed if:
- node with the same name exists in the target container
resolutionStrategyisoverwritekeepShareLinksistrue
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.createAndPreserveRoomRescueKeyPair🚀 Since v4.24.0
Description:
Create room rescue key pair and preserve copy of old private key.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Room rescue key pair is created.
Copy of old private key is preserved.Further Information:
You can submit your old private key, encrypted with your current password.
This allows migrating file keys encrypted with your old key pair to the new one. -
nodes.createFileUploadChannelDescription:
This endpoint creates a new upload channel which is the first step in any file upload workflow.
Precondition:
User has 🔓 create permissions in the parent container (room or folder).
Postcondition:
A new upload channel for a file is created.
Its ID and an upload token are returned.Further Information:
The upload ID is used for uploads with
X-Sds-Auth-Tokenheader, the upload token can be used for uploads without authentication header.Please provide the size of the intended upload so that the quota can be checked in advanced and no data is transferred unnecessarily.
Notes are limited to 255 characters.
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.createFolderDescription:
Create a new folder.
Precondition:
User has 🔓 create permissions in current room.
Postcondition:
New folder is created.
Further Information:
Folders CANNOT be created on top level (without parent element).
Notes are limited to 255 characters.Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.createNodeComment🚀 Since v4.10.0
Description:
Create a comment for a specific node.
Precondition:
User has 🔓 read permissions on the node.
Postcondition:
Comment is created.
Further Information:
Maximum allowed text length: 65535 characters.
-
nodes.createRoomDescription:
Creates a new room at the provided parent node.
Creation of top level rooms provided.Precondition:
User has 🔓 manage permissions in the parent room.
Postcondition:
A new room is created.
Further Information:
Rooms may only have other rooms as parent.
Rooms on top level do NOT have any parent.
Rooms may have rooms as children on n hierarchy levels.
If permission inheritance is disabled, there MUST be at least one admin user / group (with neither the group nor the user having an expiration date).Notes are limited to 255 characters.
Provided (or default) classification is taken from room when file gets uploaded without any classification.
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.downloadZipArchiveDescription:
Download multiple files in a ZIP archive.
Precondition:
User has 🔓 read permissions in auth parent room.
Postcondition:
Stream is returned.
Further Information:
None.
-
nodes.emptyDeletedNodesDescription:
Empty a recycle bin.
Precondition:
User has 🔓 delete recycle bin permissions in parent room.
Postcondition:
All files in the recycle bin are permanently removed.
Further Information:
Actually removes the previously deleted files from the system.
This action is irreversible. -
nodes.encryptRoomDescription:
Activates the client-side encryption for a room.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Encryption of room is activated.
Further Information:
Only empty rooms at the top level may be encrypted.
This endpoint may also be used to disable encryption of an empty room. -
nodes.generateDownloadUrlDescription:
Create a download URL to retrieve a file without
X-Sds-Auth-TokenHeader.Precondition:
User with 🔓 read permissions in parent room.
Postcondition:
Download token is generated and returned.
Further Information:
The token is necessary to access
downloadsressources. -
nodes.generateDownloadUrlForZipArchiveDescription:
Create a download URL to retrieve several files in one ZIP archive.
Precondition:
User has 🔓 read permissions in parent room.
Postcondition:
Download URL is generated and returned.
Further Information:
The token is necessary to access
downloadsresources.
ZIP download is only available for files and folders. -
nodes.generatePresignedUrlsFiles🚀 Since v4.15.0
Description:
Generate presigned URLs for S3 file upload.
Precondition:
An upload channel has been created and user has to be the creator of the upload channel.
Postcondition:
List of presigned URLs is returned.
Further Information:
The size for each part must be >= 5 MB, except for the last part.
The part number of the first part in S3 is 1 (not 0).
Use HTTP methodPUTfor uploading bytes via presigned URL. -
nodes.handleRoomWebhookAssignments🚀 Since v4.19.0
Description:
Handle room webhook assignments.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
List of webhooks is returned.
Further Information:
None.
Available event types:
Expand
-
nodes.moveNodesDescription:
Moves nodes (folder, file) to another parent.
Precondition:
Authenticated user with 🔓 read and 🔓 delete permissions in the source parent and 🔓 create permissions in the target parent node.
Postcondition:
Nodes are moved to target parent.
Further Information:
Nodes MUST be in same source parent.
Rooms CANNOT be moved.Download share id (if exists) gets changed if:
- node with the same name exists in the target container
resolutionStrategyisoverwritekeepShareLinksistrue
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.removeDeletedNodesDescription:
Permanently remove a list of nodes from the recycle bin.
Precondition:
User has 🔓 delete recycle bin permissions in parent room.
Postcondition:
All provided nodes are removed.
Further Information:
The removal of deleted nodes from the recycle bin is irreversible.
-
nodes.removeFavoriteDescription:
Unmarks a node (room, folder or file) as favorite.
Precondition:
Authenticated user is allowed to 👁 see the node (i.e.
isBrowsable = true).Postcondition:
A node gets unmarked as favorite.
Further Information:
None.
-
nodes.removeNodeDescription:
Delete node (room, folder or file).
Precondition:
Authenticated user with 🔓 delete permissions on supplied nodes (for folders or files) or on superordinated node (for rooms).
Postcondition:
Node gets deleted.
Further Information:
None.
-
nodes.removeNodeComment🚀 Since v4.10.0
Description:
Delete an existing comment for a specific node.
Precondition:
User has 🔓 read permissions on the node and is the creator of the comment OR 👤 Room Administrator in auth parent room.
Postcondition:
Comment is deleted.
Further Information:
None.
-
nodes.removeNodesDescription:
Delete nodes (room, folder or file).
Precondition:
Authenticated user with 🔓 delete permissions on supplied nodes (for folders or files) or on superordinated node (for rooms).
Postcondition:
Nodes are deleted.
Further Information:
Nodes MUST be in same parent.
-
nodes.removeRoomRescueKeyPair🚀 Since v4.24.0
Description:
Delete room rescue key pair.
Precondition:
Authenticated user.
Postcondition:
Key pair is removed (cf. further information below).
Further Information:
Please set a new room rescue key pair first and re-encrypt file keys with it.
If no version is set, deleted key pair with lowest preference value.
Although,versionSHOULD be set. -
nodes.requestDeletedNodeDescription:
Get metadata of a deleted node.
Precondition:
User can access parent room and has 🔓 read recycle bin permissions.
Postcondition:
Requested deleted node is returned.
Further Information:
None.
-
nodes.requestDeletedNodesSummaryDescription:
Retrieve a list of deleted nodes in a recycle bin.
Precondition:
User can access parent room and has 🔓 read recycle bin permissions.
Postcondition:
List of deleted nodes is returned.
Further Information:
Only room IDs are accepted as parent ID since only rooms may have a recycle bin.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
type:eq:file:folder|name:cn:searchString_1|parentPath:cn:searchString_2
Get deleted nodes where type equals (fileORfolder) AND deleted node name containingsearchString_1AND deleted node parent path containingsearchString 2.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.
Nodes are sorted by type first, then by sent sort string.Example
name:desc|timestampCreation:asc
Sort bynamedescending ANDtimestampCreationascending.Sorting options:
Expand
-
nodes.requestDeletedNodeVersionsDescription:
Retrieve all deleted versions of a node.
Precondition:
User can access parent room and has 🔓 read recycle bin permissions.
Postcondition:
List of deleted versions of a node is returned.
Further Information:
The node is identified by three parameters:
- parent ID
- name
- type (file, folder).
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
expireAt:desc|size:asc
Sort byexpireAtdescending ANDsizeascending.Sorting options:
Expand
-
nodes.requestFileVersionList🚀 Since v4.37.0
Description:
Request a list of file versions. Both nodes and deleted nodes are included, depending on the user's permissions.
Precondition:
User has 🔓 read/read recycle bin permissions in parent room.
Postcondition:
List of file versions is returned.
Further Information:
Maximum number of file versions is 500. The list is sorted by ID DESC.
-
nodes.requestListOfWebhooksForRoom🚀 Since v4.19.0
Description:
Get a list of webhooks for the room scope with their assignment status.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
List of webhooks is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
isAssigned:eq:true
Get a list of assigned webhooks to the room.Filtering options:
Expand
-
nodes.requestMissingFileKeysDescription:
Requests a list of missing file keys that may be generated by the current user.
Precondition:
User has a key pair.
Only returns users that owns one of the following permissions: 🔓 manage, 🔓 read, 🔓 manage download sharePostcondition:
None.
Further Information:
Clients SHOULD regularly request missing file keys to provide access to files for other users.
The returned list is ordered by priority (emergency passwords / rescue keys are returned first). There is an enforced limit of 100 items per request. A total value greater than limit signals that there are more entries but does not necessarily reflect the precise number of total items. -
nodes.requestNodeDescription:
Get node (room, folder or file).
Precondition:
User has 🔓 read permissions in auth parent room.
Postcondition:
Requested node is returned.
Further Information:
None.
-
nodes.requestNodeComments🚀 Since v4.10.0
Description:
Get comments for a specific node.
Precondition:
User has 🔓 read permissions on the node.
Postcondition:
List with comments (sorted by
createdAttimestamp) is returned.Further Information:
An empty list is returned if no comments were found.
Output is limited to 500 entries.
For more results please use filter criteria and paging (offset+limit). -
nodes.requestNodeParents🚀 Since v4.10.0
Description:
Requests a list of node ancestors, sorted from root node to the node's direct parent node.
Precondition:
User is allowed to browse through the node tree until the requested node.
Postcondition:
List of parent nodes is returned.
Further Information:
None.
-
nodes.requestNodesDescription:
Provides a hierarchical list of file system nodes (rooms, folders or files) of a given parent that are accessible by the current user.
Precondition:
Authenticated user.
Postcondition:
List of nodes is returned.
Further Information:
EncryptionInfois NOT provided.Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
type:eq:room:folder|perm:eq:read
Get nodes where type equals (roomORfolder) AND user hasreadpermissions.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.
Nodes are sorted by type first, then by sent sort string.Example
name:desc|fileType:asc
Sort bynamedescending ANDfileTypeascending.Sorting options:
Expand
Deprecated sorting options:
Expand
-
nodes.requestPendingAssignmentsDescription:
Requests a list of user-room assignments by groups that have NOT been approved yet
These can have the state:- WAITING
- DENIED
- ACCEPTED
ACCEPTED assignments are already removed from the list.
Precondition:
None.
Postcondition:
List of user-room assignments is returned.
Further Information:
Room administrators SHOULD regularly request pending assingments to provide access to rooms for other users.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
state:eq:WAITING
Filter assignments by stateWAITING.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
userId:desc|state:asc
Sort byuserIddescending ANDstateascending.Sorting options:
Expand
-
nodes.requestRoomActivitiesLogAsJson🚀 Since v4.3.0
Description:
Retrieve syslog (audit log) events related to a room.
Precondition:
Requires 🔓 read permissions on that room.
Postcondition:
List of events is returned.
Further Information:
Output may be limited to a certain number of entries.
Please use filter criteria and paging.Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
time:desc
Sort bytimedescending (default sort option).Sorting options:
Expand
-
nodes.requestRoomGroupsDescription:
Retrieve a list of groups that are and / or can be granted to the room.
Precondition:
Any permissions on target room.
Postcondition:
List of groups is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isGranted:eq:false|name:cn:searchString
Get all groups that are NOT granted to this room AND whose name is likesearchString.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
name:desc
Sort bynamedescending.Sorting options:
Expand
-
nodes.requestRoomPolicies🚀 Since v4.32.0
Description:
Retrieve the room policies:
defaultExpirationPeriod
Precondition:
User has 🔓 read permissions in that room.
Postcondition:
Room Policies returned.
Further Information:
defaultExpirationPeriod: Default policy room expiration period in seconds. All existing and future files in a room will have their expiration date set to this period after their respective upload. Existing files can be set to expire earlier afterwards.0means no default expiration policy will be enforced. -
nodes.requestRoomRescueKey🚧 Deprecated since v4.24.0
Description:
Returns the file key for the room emergency password / rescue key of a certain file (if available).
Precondition:
User with 🔓 read permissions in parent room.
Postcondition:
File key is returned.
Further Information:
None.
-
nodes.requestRoomRescueKeyPairDescription:
Retrieve the room rescue key pair.
Precondition:
User has 🔓 read permissions in that room.
Postcondition:
Key pair is returned.
Further Information:
None.
-
nodes.requestRoomRescueKeyPairs🚀 Since v4.24.0
Description:
Retrieve all room rescue key pairs to allow migrating room-rescue-key-encrypted file keys.
Precondition:
User has 🔓 read permissions in that room.
Postcondition:
List of key pairs is returned.
Further Information:
In the case of an algorithm migration to a room rescue key pair, one should create the new key pair before deleting the old one. This allows re-encrypting file keys with the new key pair, using the old one.
This API allows to retrieve both key pairs, in contrast to
GET /nodes/rooms/{room_id}/keypair, which only delivers the preferred one. -
nodes.requestRoomS3Tags🚀 Since v4.9.0
Description:
Retrieve a list of S3 tags assigned to a room.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
List of assigned S3 tags is returned.
Further Information:
None.
-
nodes.requestRoomUsersDescription:
Retrieve a list of users that are and / or can be granted to the room.
Precondition:
Any permissions on target room.
Postcondition:
None.
Further Information:
List of users is returned.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
permissionsManage:eq:true|user:cn:searchString
Get all users that havemanagepermissions to this room AND whose (firstNameORlastNameORemailORusername) is likesearchString.Filtering options:
Expand
Deprecated filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
user:desc
Sort byuserdescending.Sorting options:
Expand
-
nodes.requestSystemRescueKey🚧 Deprecated since v4.24.0
Description:
Returns the file key for the system emergency password / rescue key of a certain file (if available).
Precondition:
User with 🔓 read permissions in parent room.
Postcondition:
File key is returned.
Further Information:
None.
-
nodes.requestUploadStatusFiles🚀 Since v4.15.0
Description:
Request status of a S3 file upload.
Precondition:
An upload channel has been created and user has to be the creator of the upload channel.
Postcondition:
Status of S3 multipart upload request is returned.
Further Information:
None.
Possible errors:
Expand
-
nodes.requestUserFileKeyDescription:
Returns the file key for the current user (if available).
Precondition:
User with one of the following permissions in parent room: 🔓 manage, 🔓 read, 🔓 manage download share
Postcondition:
File key is returned.
Further Information:
The symmetric file key is encrypted with the user's public key.
File keys are generated with the workflow "Generate file keys" that starts atGET /nodes/missingFileKeys. -
nodes.restoreNodesDescription:
Restore a list of deleted nodes.
Precondition:
User has 🔓 create permissions in parent room and 🔓 restore recycle bin permissions.
Postcondition:
The selected files are moved from the recycle bin to the chosen productive container.
Further Information:
If no parent ID is provided, the node is restored to its previous location.
The default resolution strategy isautorenamethat adds numbers to the file name until the conflict is solved.
If an existing file is overwritten, it is moved to the recycle bin instead of the restored one.Download share id (if exists) gets changed if:
- node with the same name exists in the target container
resolutionStrategyisoverwritekeepShareLinksistrue
-
nodes.revokeRoomGroupsDescription:
Revoke granted groups from room.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Group's permissions are revoked.
Further Information:
Batch function.
-
nodes.revokeRoomUsersDescription:
Revoke granted users from room.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
User's permissions are revoked.
Further Information:
Batch function.
-
nodes.searchNodesDescription:
Provides a flat list of file system nodes (rooms, folders or files) of a given parent that are accessible by the current user.
Precondition:
Authenticated user is allowed to 👁 see nodes (i.e.
isBrowsable = true).Postcondition:
List of nodes is returned.
Further Information:
Output is limited to 500 entries.
For more results please use filter criteria and paging (offset+limit).
EncryptionInfois NOT provided.
Wildcard character is the asterisk character:*Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
type:eq:file|createdAt:ge:2015-01-01
Get nodes where type equalsfileAND file creation date is >=2015-01-01.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
name:desc|size:asc
Sort bynamedescending ANDsizeascending.Sorting options:
Expand
Deprecated sorting options:
Expand
-
nodes.setRoomPolicies🚀 Since v4.32.0
Description:
Retrieve the room policies:
defaultExpirationPeriod
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Room policy is set.
Further Information:
defaultExpirationPeriod: Default policy room expiration period in seconds. All existing and future files in a room will have their expiration date set to this period after their respective upload. Existing files can be set to expire earlier afterwards.0means no default expiration policy will be enforced. This removes all expiration dates from existing files. -
nodes.setRoomRescueKeyPair🚀 Since v4.24.0
Description:
Set room rescue key pair.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Key pair is set.
Further Information:
Room rescue key pair can be used to upgrade algorithm.
-
nodes.setRoomS3Tags🚀 Since v4.9.0
Description:
Set S3 tags to a room.
Precondition:
User needs to be a 👤 Room Administrator.
Postcondition:
Provided S3 tags are assigned to a room.
Further Information:
Every request overrides current S3 tags.
Mandatory S3 tag IDs MUST be sent. -
nodes.setUserFileKeysDescription:
Sets symmetric file keys for several users and files.
Precondition:
User has file keys for the files.
Only settable by users that own one of the following permissions: 🔓 manage, 🔓 read, 🔓 manage download share, 🔓 change configPostcondition:
Stores new file keys for other users.
Further Information:
Only users with copies of the file key (encrypted with their public keys) can access a certain file.
This endpoint is used for the distribution of file keys amongst an authorized user base.
User can set file key for himself.
The users who already have a file key are ignored and keep the distributed file key -
nodes.updateFavorites🚀 Since v4.25.0
Description:
Marks or unmarks a list of nodes (room, folder or file) as favorite.
Precondition:
Authenticated user is allowed to 👁 see the node (i.e.
isBrowsable = true).Postcondition:
Nodes gets marked as favorite.
Further Information:
Maximum number of nodes is 200.
-
nodes.updateFileDescription:
Updates a list of file’s metadata.
Precondition:
User has 🔓 change permissions in parent room.
Postcondition:
File's metadata is changed.
-
nodes.updateFiles🚀 Since v4.25.0
Description:
Updates a list of file’s metadata.
Precondition:
User has 🔓 change permissions in parent room.
Postcondition:
File's metadata is changed.
Further Information:
Maximum number of files is 200
-
nodes.updateFolderDescription:
Updates folder’s metadata.
Precondition:
User has 🔓 change permissions in parent room.
Postcondition:
Folder's metadata is changed.
Further Information:
Notes are limited to 255 characters.
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.updateNodeComment🚀 Since v4.10.0
Description:
Edit the text of an existing comment for a specific node.
Precondition:
User has 🔓 read permissions on the node and is the creator of the comment.
Postcondition:
Comments text gets changed.
Further Information:
Maximum allowed text length: 65535 characters.
-
nodes.updateRoomDescription:
Updates room’s metadata.
Precondition:
User is a 👤 Room Administrator at superordinated level.
Postcondition:
Room's metadata is changed.
Further Information:
Notes are limited to 255 characters.
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
nodes.updateRoomGroupsDescription:
All existing group permissions will be overwritten.
Precondition:
User needs to be a 👤 Room Administrator. To add new members, the user needs the right 🔓 non-members add, which is included in any role.
Postcondition:
Group's permissions are changed.
Further Information:
Batch function.
-
nodes.updateRoomUsersDescription:
All existing user permissions will be overwritten.
Precondition:
User needs to be a 👤 Room Administrator. To add new members, the user needs the right 🔓 non-members add, which is included in any role.
Postcondition:
User's permissions are changed.
Further Information:
Batch function.
-
nodes.uploadFileAsMultipart🚧 Deprecated since v4.9.0
Use
uploadsAPIDescription:
Uploads a file or parts of it in an active upload channel.
Precondition:
An upload channel has been created.
Postcondition:
A file or parts of it are uploaded to a temporary location.
Further Information:
This endpoints supports chunked upload.
Following
Content-Typesare supported by this API:multipart/form-data- provided
Content-Type
For both file upload types set the correct
Content-Typeheader and body.Examples:
multipart/form-data
- any other
Content-Type
POST /api/v4/nodes/files/uploads/{upload_id} HTTP/1.1 Header:...Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW... Body:------WebKitFormBoundary7MA4YWxkTrZu0gWContent-Disposition: form-data; name="file"; filename="file.txt"Content-Type: text/plain Content of file.txt------WebKitFormBoundary7MA4YWxkTrZu0gW--POST /api/v4/nodes/files/uploads/{upload_id} HTTP/1.1 Header:...Content-Type: { ... }... Body:raw content -
provisioning.createCustomerDescription:
Create a new customer.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.Postcondition:
A new customer is created.
Further Information:
If no company name is set, first letter of the first name separated by dot followed by last name of the first administrator is used (e.g.
J.Doe).
Max quota has to be at least1 MB(=1.048.576 B).If
basicauthentication is enabled, the first administrator will getbasicauthentication by default.
To create a first administrator withoutbasicauthentication it MUST be disabled explicitly.Forbidden characters in passwords: [
&,',<,>]Authentication Method Options:
Expand
-
provisioning.createTenantWebhook🚀 Since v4.19.0
Description:
Create a new webhook for the tenant scope.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
Webhook is created for given event types.
Further Information:
URL must begin with the
HTTPSscheme. Webhook names are limited to 150 characters.Available event types:
Expand
-
provisioning.removeCustomerDescription:
Delete a customer.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.Postcondition:
Customer is deleted.
Further Information:
None.
-
provisioning.removeCustomerAttribute🚀 Since v4.4.0
Description:
Delete a custom customer attribute.
Precondition:
Right 🔓 change global config required.
Postcondition:
Custom customer attribute gets deleted.
Further Information:
- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive.
- Allowed characters for keys are:
-
provisioning.removeTenantWebhook🚀 Since v4.19.0
Description:
Delete a webhook for the tenant scope.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
Webhook is deleted.
Further Information:
None.
-
provisioning.requestCustomerDescription:
Receive details of a selected customer.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.Postcondition:
Customer details are returned.
Further Information:
None.
-
provisioning.requestCustomerAttributes🚀 Since v4.4.0
Description:
Retrieve a list of customer attributes.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.
Right 🔓 read all customers required.Postcondition:
List of attributes is returned.
Further Information:
Filtering:
Filters are case insensitive.
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
key:cn:searchString_1|value:cn:searchString_2
Filter by attribute key containssearchString_1AND attribute value containssearchString_2.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
key:asc|value:desc
Sort bykeyascending AND byvaluedescending.Sorting options:
Expand
-
provisioning.requestCustomersDescription:
Receive a list of customers.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.Postcondition:
List of customers is returned.
Further Information:
This list returns a maximum of 1000 entries.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
trialDaysLeft:le:10|userMax:le:100
Get all customers with10trial days left AND user maximum <=100.Filtering options:
Expand
Deprecated filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
companyName:desc|userUsed:asc
Sort bycompanyNamedescending ANDuserUsedascending.Sorting options:
Expand
Deprecated sorting options:
Expand
-
provisioning.requestCustomerUsersDescription:
Receive a list of users associated with a certain customer.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.Postcondition:
List of customer users is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Except forlogin,firstNameandlastName- these are connected via logical disjunction (OR)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
login:cn:searchString_1|firstName:cn:searchString_2|lockStatus:eq:2
Filter users by login containssearchString_1OR firstName containssearchString_2AND those who are NOT locked.Filtering options:
Expand
Deprecated filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
firstName:asc|lastLoginSuccessAt:desc
Sort byfirstNameascending AND bylastLoginSuccessAtdescending.Sorting options:
Expand
Deprecated sorting options:
Expand
-
provisioning.requestListOfEventTypesForTenant🚀 Since v4.19.0
Description:
Get a list of available event types.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
List of available event types is returned.
Further Information:
None.
-
provisioning.requestListOfTenantWebhooks🚀 Since v4.19.0
Description:
Get a list of webhooks for the tenant scope.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
List of webhooks is returned.
Further Information:
Output is limited to 500 entries.
For more results please use filter criteria and paging (offset+limit).
EncryptionInfois NOT provided.
Wildcard character is the asterisk character:*Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
name:cn:goo|createdAt:ge:2015-01-01
Get webhooks where name containsgooAND webhook creation date is >=2015-01-01.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
name:desc|isEnabled:asc
Sort bynamedescending andisEnabledascending.Sorting options:
Expand
-
provisioning.requestTenantWebhook🚀 Since v4.19.0
Description:
Get a specific webhook for the tenant scope.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
Webhook is returned.
Further Information:
None.
-
provisioning.resetTenantWebhookLifetime🚀 Since v4.19.0
Description:
Reset the lifetime of a webhook for the tenant scope.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
Lifetime of the webhook is reset.
Further Information:
None.
-
provisioning.setCustomerAttributes🚧 Deprecated since v4.28.0
Description:
Set custom customer attributes.
Precondition:
Right 🔓 change global config required.
Postcondition:
Custom customer attributes gets set.
Further Information:
Batch function.
All existing customer attributes will be deleted.- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive.
- Allowed characters for keys are:
-
provisioning.updateCustomerDescription:
Change selected attributes of a customer.
Precondition:
Authentication with
X-Sds-Service-Tokenrequired.Postcondition:
Selected attributes of customer are updated.
Further Information:
None.
-
provisioning.updateCustomerAttributes🚀 Since v4.4.0
Description:
Add or edit custom customer attributes.
🚧 Warning: Please note that the response with HTTP status code 200 (OK) is deprecated and will be replaced with HTTP status code 204 (No content)!Precondition:
Right 🔓 change global config required.
Postcondition:
Custom customer attributes get added or edited.
Further Information:
Batch function.
If an entry exists before, it will be overwritten.- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive.
- Allowed characters for keys are:
-
provisioning.updateTenantWebhook🚀 Since v4.19.0
Description:
Update an existing webhook for the tenant scope.
Precondition:
Right 🔓 manage webhook required.
Postcondition:
Webhook is updated.
Further Information:
URL must begin with the
HTTPSscheme. Webhook names are limited to 150 characters.Available event types:
Expand
-
public.cancelFileUploadViaShareDescription:
Abort (chunked) upload via Upload Share.
Precondition:
Valid Upload ID.
Postcondition:
Aborts upload and invalidates upload ID / token.
Further Information:
None.
-
public.checkPublicDownloadSharePassword🚀 Since v4.36.0
Description:
Check password for a public Download Share
Precondition:
None.
Postcondition:
None.
Further Information:
None.
-
public.completeFileUploadViaShareDescription:
Finalize (chunked) upload via Upload Share.
Precondition:
Valid upload ID.
Only returns users that owns one of the following permissions: 🔓 manage, 🔓 read, 🔓 manage download share, 🔓 manage upload sharePostcondition:
Finalizes upload.
Further Information:
Chunked uploads (range requests) are supported.
Please ensure that all chunks have been transferred correctly before finishing the upload.
If file hash has been created in time a201 Createdwill be responded and hash will be part of response, otherwise it will be a202 Acceptedwithout it. -
public.completeS3FileUploadViaShare🚀 Since v4.15.0
Description:
Finishes a S3 file upload and closes the corresponding upload channel.
Precondition:
Valid upload ID.
Only returns users that owns one of the following permissions: 🔓 manage, 🔓 read, 🔓 manage download share, 🔓 manage upload sharePostcondition:
Upload channel is closed. S3 multipart upload request is completed.
Further Information:
None.
-
public.createShareUploadChannelDescription:
Create a new upload channel.
Precondition:
None.
Postcondition:
Upload channel is created and corresponding upload URL, token & upload ID are returned.
Further Information:
Use
uploadUrlthe uploadtokenis deprecated.Please provide the size of the intended upload so that the quota can be checked in advanced and no data is transferred unnecessarily.
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
public.downloadFileViaTokenPublicDescription:
Download a file (or zip archive if target is a folder or room).
Precondition:
Valid download token.
Postcondition:
Stream is returned.
Further Information:
Range requests are supported.
Range requests are illegal for zip archive download. -
public.downloadFileViaTokenPublic1Description:
Download a file (or zip archive if target is a folder or room).
Precondition:
Valid download token.
Postcondition:
Stream is returned.
Further Information:
Range requests are supported.
Range requests are illegal for zip archive download. -
public.generateDownloadUrlPublicDescription:
Generate a download URL to retrieve a shared file.
Precondition:
None.
Postcondition:
Download URL and token are generated and returned.
Further Information:
Use
downloadUrlthe downloadtokenis deprecated. -
public.generatePresignedUrlsPublic🚀 Since v4.15.0
Description:
Generate presigned URLs for S3 file upload.
Precondition:
Valid upload ID
Postcondition:
List of presigned URLs is returned.
Further Information:
The size for each part must be >= 5 MB, except for the last part.
The part number of the first part in S3 is 1 (not 0).
Use HTTP methodPUTfor uploading bytes via presigned URL. -
public.requestActiveDirectoryAuthInfoDescription:
Provides information about Active Directory authentication options.
Precondition:
None.
Postcondition:
Active Directory authentication options information is returned.
Further Information:
None.
-
public.requestOpenIdAuthInfoDescription:
Provides information about OpenID Connect authentication options.
Precondition:
None.
Postcondition:
OpenID Connect authentication options information is returned.
Further Information:
None.
-
public.requestPublicDownloadShareInfoDescription:
Retrieve the public information of a Download Share.
Precondition:
None.
Postcondition:
Download Share information is returned.
Further Information:
None.
-
public.requestPublicUploadShareInfoDescription:
Provides information about the desired Upload Share.
Precondition:
Only
userUserPublicKeyListis returned to the users who owns one of the following permissions: 🔓 manage, 🔓 read, 🔓 manage download share, 🔓 manage upload sharePostcondition:
None.
Further Information:
If no password is set, the returned information is reduced to the following attributes (if available):
namecreatedAtisProtectedisEncryptedshowUploadedFilesuserUserPublicKeyList(if parent is end-to-end encrypted)
Only if the password is transmitted as
X-Sds-Share-Passwordheader, all values are returned. -
public.requestSoftwareVersionDescription:
Public software version information.
Precondition:
None.
Postcondition:
Sofware version information is returned.
Further Information:
The version of DRACOON Server consists of two components:
- API
- Core (referred to as "Server")
which are versioned individually.
-
public.requestSystemInfoDescription:
Provides information about system.
Precondition:
None.
Postcondition:
System information is returned.
Further Information:
Authentication methods are sorted by priority attribute.
Smaller values have higher priority.
Authentication method with highest priority is considered as default.System information:
Expand
Authentication methods:
Expand
-
public.requestSystemTimeDescription:
Retrieve the actual server time.
Precondition:
None.
Postcondition:
Server time is returned.
Further Information:
None.
-
public.requestThirdPartyDependencies🚀 Since v4.9.0
Description:
Provides information about used third-party software dependencies.
Precondition:
None.
Postcondition:
List of the third-party software dependencies used by DRACOON Core (referred to as "Server") is returned.
Further Information:
None.
-
public.requestUploadStatusPublic🚀 Since v4.15.0
Description:
Request status of a S3 file upload.
Precondition:
An upload channel has been created and the user has 🔓 create permissions in the parent container (room or folder).
Postcondition:
Status of S3 multipart upload request is returned.
Further Information:
None.
Possible errors:
Expand
-
public.uploadFileAsMultipartPublic1Description:
Chunked upload of files via Upload Share.
Precondition:
Valid upload ID.
Postcondition:
Chunk of file is uploaded.
Further Information:
Chunked uploads (range requests) are supported.
Following
Content-Typesare supported by this API:multipart/form-data- provided
Content-Type
For both file upload types set the correct
Content-Typeheader and body.Examples:
multipart/form-data
- any other
Content-Type
POST /api/v4/public/shares/uploads/{access_key}{upload_id} HTTP/1.1 Header:...Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW... Body:------WebKitFormBoundary7MA4YWxkTrZu0gWContent-Disposition: form-data; name="file"; filename="file.txt"Content-Type: text/plain Content of file.txt------WebKitFormBoundary7MA4YWxkTrZu0gW--POST /api/v4/public/shares/uploads/{access_key}{upload_id} HTTP/1.1 Header:...Content-Type: { ... }... Body:raw content -
resources.requestSubscriptionScopes🚀 Since v4.20.0
Description:
Retrieve a list of subscription scopes.
Precondition:
Authenticated user.
Postcondition:
List of scopes is returned.
Further Information:
None.
-
resources.requestUserAvatarDescription:
Get user avatar.
Precondition:
Valid user ID and avatar UUID
Postcondition:
Avatar is returned.
Further Information:
None.
-
roles.addRoleGroupsDescription:
Assign group(s) to a role.
Precondition:
Right 🔓 grant permission on desired role required.
Postcondition:
One or more groups will be added to a role.
Further Information:
None.
-
roles.addRoleUsersDescription:
Assign user(s) to a role.
Precondition:
Right 🔓 grant permission on desired role required.
Postcondition:
One or more users will be added to a role.
Further Information:
None.
-
roles.requestRoleGroupsDescription:
Get all groups with a specific role.
Precondition:
Right 🔓 read groups required.
Postcondition:
List of to the role assigned groups is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isMember:eq:false|name:cn:searchString
Get all groups that are NOT a member of that role AND whose name containssearchString.Filtering options:
Expand
-
roles.requestRolesDescription:
Retrieve a list of all roles with assigned rights.
Precondition:
Right 🔓 read users required.
Postcondition:
List of roles with assigned rights is returned.
Further Information:
None.
-
roles.requestRoleUsersDescription:
Get all users with a specific role.
Precondition:
Right 🔓 read users required.
Postcondition:
List of users is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isMember:eq:false|user:cn:searchString
Get all users that are NOT member of that role AND whose (firstNameORlastNameORemailORusername) is likesearchString.Filtering options:
Expand
Deprecated filtering options:
Expand
-
roles.revokeRoleGroupsDescription:
Revoke granted group(s) from a role.
Precondition:
Right 🔓 grant permission on desired role required.
For each role, at least one non-expiring user MUST remain who may grant the role.Postcondition:
One or more groups will be removed from a role.
Further Information:
None.
-
roles.revokeRoleUsersDescription:
Revoke granted user(s) from a role.
Precondition:
Right 🔓 grant permission on desired role required.
For each role, at least one non-expiring user MUST remain who may grant the role.Postcondition:
One or more users will be removed from a role.
Further Information:
None.
-
settings.createAndPreserveKeyPair🚀 Since v4.24.0
Description:
Create system rescue key pair and preserve copy of old private key.
Precondition:
- Right 🔓 change config
- Existence of own key pair
Postcondition:
System rescue key pair is created.
Copy of old private key is preserved.Further Information:
You can submit your old private key, encrypted with your current password.
This allows migrating file keys encrypted with your old key pair to the new one. -
settings.createWebhook🚀 Since v4.19.0
Description:
Create a new webhook for the customer scope.
Precondition:
Right 🔓 change config required.
Postcondition:
Webhook is created for given event types.
Further Information:
URL must begin with the
HTTPSscheme.
Webhook names are limited to 150 characters.Available event types:
Expand
-
settings.removeSystemRescueKeyPair🚀 Since v4.24.0
Description:
Remove the system rescue key pair.
Precondition:
- Right 🔓 change config
- Existence of own key pair
Postcondition:
Key pair is removed (cf. further information below).
Further Information:
Please set a new system rescue key pair first and re-encrypt file keys with it.
If no version is set, deleted key pair with lowest preference value.
Although,versionSHOULD be set. -
settings.removeWebhook🚀 Since v4.19.0
Description:
Delete a webhook for the customer scope.
Precondition:
Right 🔓 change config required.
Postcondition:
Webhook is deleted.
Further Information:
None.
-
settings.requestAllSystemRescueKeyPairs🚀 Since v4.24.0
Description:
Retrieve all system rescue key pairs to allow migrating system-rescue-key-encrypted file keys.
Precondition:
- Right 🔓 change config
- Existence of own key pair
Postcondition:
List of key pairs is returned.
Further Information:
In the case of an algorithm migration of a system rescue key, one should create the new key pair before deleting the old one.
This allows re-encrypting file keys with the new key pair, using the old one.This API allows to retrieve both key pairs, in contrast to
GET /settings/keypair, which only delivers the preferred one. -
settings.requestListOfEventTypesForConfigManager🚀 Since v4.19.0
Description:
Get a list of available (for 👤 Config Manager) event types.
Precondition:
Right 🔓 change config required.
Postcondition:
List of available event types is returned.
Further Information:
None.
-
settings.requestListOfWebhooks🚀 Since v4.19.0
Description:
Get a list of webhooks for the customer scope.
Precondition:
Right 🔓 change config required.
Postcondition:
List of webhooks is returned.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
name:cn:goo|createdAt:ge:2015-01-01
Get webhooks where name containsgooAND webhook creation date is >=2015-01-01.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
name:desc|isEnabled:asc
Sort bynamedescending andisEnabledascending.Sorting options:
Expand
-
settings.requestNotificationChannels🚀 Since v4.20.0
Description:
Retrieve a list of configured notification channels.
Precondition:
Right "change config" required.
Postcondition:
List of notification channels is returned.
Further Information:
None.
-
settings.requestSettingsDescription:
Retrieve customer related settings.
Precondition:
Right 🔓 read config required.
Postcondition:
List of available settings is returned.
Further Information:
None.
Configurable customer settings:
Expand
-
settings.requestSystemRescueKeyPair🚀 Since v4.24.0
Description:
Retrieve the system rescue key pair.
Precondition:
Right 🔓 change config
Postcondition:
Key pair is returned.
Further Information:
If more than one key pair exists the one with highest preference value is returned.
-
settings.requestWebhook🚀 Since v4.19.0
Description:
Get a specific webhook for the customer scope.
Precondition:
Right 🔓 change config required.
Postcondition:
Webhook is returned.
Further Information:
None.
-
settings.resetWebhookLifetime🚀 Since v4.19.0
Description:
Reset the lifetime of a webhook for the customer scope.
Precondition:
Right 🔓 change config required.
Postcondition:
Lifetime of the webhook is reset.
Further Information:
None.
-
settings.setSettingsDescription:
Set customer related settings.
Precondition:
Right 🔓 change global config and role 👤 Config Manager required.
Postcondition:
Provided settings are updated.
Further Information:
None.
Configurable customer settings
Expand
Node naming convention:
- Node (room, folder, file) names are limited to 150 characters.
- Illegal names:
'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9', (and any of those with an extension) - Illegal characters in names:
'\\', '<','>', ':', '\"', '|', '?', '*', '/', leading '-', trailing '.'
-
settings.setSystemRescueKeyPair🚀 Since v4.24.0
Description:
Set the system rescue key pair and activate client-side encryption for according customer.
Precondition:
- Right 🔓 change config
- Existence of own key pair
Postcondition:
System rescue key pair is set and client-side encryption is enabled.
Further Information:
Sets the ability for this customer to encrypt rooms.
Once enabled on customer level, it CANNOT be unset.
On activation, a customer rescue key pair MUST be set. -
settings.toggleNotificationChannels🚀 Since v4.20.0
Description:
Toggle configured notification channels.
Precondition:
Right "change config" required.
Postcondition:
Channel status is switched.
Further Information:
None.
-
settings.updateWebhook🚀 Since v4.19.0
Description:
Update an existing webhook for the customer scope.
Precondition:
Right 🔓 change config required.
Postcondition:
Webhook is updated.
Further Information:
URL must begin with the
HTTPSscheme. Webhook names are limited to 150 characters. Webhook event types can not be changed from Customer Admin Webhook types to Node Webhook types and vice versaAvailable event types:
Expand
-
shares.createDownloadShareDescription:
Create a new Download Share.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Share is created.
Further Information:
If the target node is a room: subordinary rooms are excluded from a Download Share.
nameis limited to 150 characters.notesare limited to 255 characters.passwordis limited to 1024 characters.
Use
POST /shares/downloads/{share_id}/emailAPI for sending emails.Forbidden characters in passwords: [
&,',<,>]Please keep in mind that due to various restrictions of different telecommunication providers, non-ASCII characters may not be displayed correctly in short messages (SMS).
-
shares.createUploadShareDescription:
Create a new Upload Share (aka File Request).
Precondition:
User has 🔓 manage upload share permissions on target container.
Postcondition:
Upload Share is created.
Further Information:
nameis limited to 150 characters.notesare limited to 255 characters.passwordis limited to 1024 characters.
Forbidden characters in passwords: [
&,',<,>]Use
POST /shares/uploads/{share_id}/emailAPI for sending emails.Please keep in mind that due to various restrictions of different telecommunication providers, non-ASCII characters may not be displayed correctly in short messages (SMS).
-
shares.deleteDownloadShares🚀 Since v4.21.0
Functional Description:
Delete multiple Download Shares.
Precondition:
User with "manage download share" permissions on target nodes.
Postcondition:
Download Shares are deleted.
Further Information:
Only the Download Shares are removed; the referenced files or containers persists.
-
shares.deleteUploadShares🚀 Since v4.21.0
Functional Description:
Delete multiple Upload Shares (aka Upload Accounts).
Precondition:
User has "manage upload share" permissions on target containers.
Postcondition:
Upload Shares are deleted.
Further Information:
Only the Upload Shares are removed; already uploaded files and the target container persist.
-
shares.removeDownloadShareDescription:
Delete a Download Share.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Share is deleted.
Further Information:
Only the Download Share is removed; the referenced file or container persists.
-
shares.removeUploadShareDescription:
Delete an Upload Share (aka File Request).
Precondition:
User has 🔓 manage upload share permissions on target container.
Postcondition:
Upload Share is deleted.
Further Information:
Only the Upload Share is removed; already uploaded files and the target container persist.
-
shares.requestDownloadShareDescription:
Retrieve detailed information about one Download Share.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Share is returned
Further Information:
None.
-
shares.requestDownloadShareQrDescription:
Retrieve detailed information about one Download Share.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Share is returned
Further Information:
None.
-
shares.requestDownloadSharesDescription:
Retrieve a list of Download Shares.
Precondition:
Authenticated user.
Postcondition:
List of available Download Shares is returned.
Further Information:
Filtering:
All filter fields are connected via logical (AND). createdBy and updatedBy searches several user-related attributes.
Filter string syntax:
FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
name:cn:searchString_1|createdBy:cn:searchString_2Filter by file name containssearchString_1AND creator info (firstNameORlastNameORemailORusername) containssearchString_2.Filtering options:
Expand
Deprecated filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
name:asc|expireAt:desc
Sort bynameascending AND byexpireAtdescending.Sorting options:
Expand
-
shares.requestUploadShareDescription:
Retrieve detailed information about one Upload Share (aka File Request).
Precondition:
User has 🔓 manage upload share permissions on target container.
Postcondition:
Upload Share is returned.
Further Information:
None.
-
shares.requestUploadShareQrDescription:
Retrieve detailed information about one Upload Share (aka File Request).
Precondition:
User has 🔓 manage upload share permissions on target container.
Postcondition:
Upload Share is returned.
Further Information:
None.
-
shares.requestUploadSharesDescription:
Retrieve a list of Upload Shares (aka File Requests).
Precondition:
Authenticated user.
Postcondition:
List of available Upload Shares is returned.
Further Information:
Filtering:
All filter fields are connected via logical (AND). createdBy and updatedBy searches several user-related attributes. Filter string syntax:
FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
name:cn:searchString_1|createdBy:cn:searchString_2
Filter by alias name containssearchString_1AND creator info (firstNameORlastNameORemailORusername) containssearchString_2.Filtering options:
Expand
Deprecated filtering options:
Expand
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
name:asc|expireAt:desc
Sort bynameascending AND byexpireAtdescending.Sorting options:
Expand
-
shares.sendDownloadShareLinkViaEmail🚀 Since v4.11.0
Description:
Send an email to specific recipients for existing Download Share.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Share link successfully sent.
Further Information:
- Forbidden characters in the email body: [
<,>]
- Forbidden characters in the email body: [
-
shares.sendUploadShareLinkViaEmail🚀 Since v4.11.0
Description:
Send an email to specific recipients for existing Upload Share.
Precondition:
User with 🔓 manage upload share permissions on target container.
Postcondition:
Upload Share link successfully sent.
Further Information:
- Forbidden characters in the email body: [
<,>]
- Forbidden characters in the email body: [
-
shares.updateDownloadShare🚀 Since v4.11.0
Description:
Update an existing Download Share.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Share is successfully updated.
Further Information:
nameis limited to 150 characters.notesare limited to 255 characters.passwordis limited to 1024 characters.
Forbidden characters in passwords: [
&,',<,>]Please keep in mind that due to various restrictions of different telecommunication providers, non-ASCII characters may not be displayed correctly in short messages (SMS).
-
shares.updateDownloadShares🚀 Since v4.25.0
Description:
Update a list of existing Download Shares.
Precondition:
User with 🔓 manage download share permissions on target node.
Postcondition:
Download Shares are successfully updated.
Further Information:
Maximum number of shares is 200
-
shares.updateUploadShare🚀 Since v4.11.0
Description:
Update existing Upload Share (aka File Request).
Precondition:
User has 🔓 manage upload share permissions on target container.
Postcondition:
Upload Share successfully updated.
Further Information:
nameis limited to 150 characters.notesare limited to 255 characters.passwordis limited to 1024 characters.
Forbidden characters in passwords: [
&,',<,>]Please keep in mind that due to various restrictions of different telecommunication providers, non-ASCII characters may not be displayed correctly in short messages (SMS).
-
shares.updateUploadShares🚀 Since v4.25.0
Description:
Update a list of existing Upload Shares (aka File Request).
Precondition:
User has 🔓 manage upload share permissions on target container.
Postcondition:
Upload Shares successfully updated.
Further Information:
Maximum number of shares is 200
-
systemAuthConfig.createAdConfigDescription:
Create a new Active Directory configuration.
Precondition:
Right 🔓 change global config of the Provider Customer required.
Postcondition:
New Active Directory configuration created.
Further Information:
None.
-
systemAuthConfig.createOAuthClientDescription:
Create a new OAuth client.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
New OAuth client created.
Further Information:
Client secret MUST have:
- at least 12 characters, at most 32 characters
- only lower case characters, upper case characters and digits
- at least 1 lower case character, 1 upper case character and 1 digit
The client secret is optional and will be generated if it is left empty.
Valid grant types are:
authorization_codeimplicitpasswordclient_credentialsrefresh_token
Grant type
client_credentialsis currently NOT permitted!Allowed characters for client ID are:
[a-zA-Z0-9_-]If grant types
authorization_codeorimplicitare used, a redirect URI MUST be provided!Default access token validity: 8 hours
Default refresh token validity: 30 days Default approval validity: ½ year -
systemAuthConfig.createOpenIdIdpConfigDescription:
Create new OpenID Connect IDP configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
New OpenID Connect IDP configuration is created.
Further Information:
None.
-
systemAuthConfig.createRadiusConfigDescription:
Create new RADIUS configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
New RADIUS configuration is created.
Further Information:
None.
-
systemAuthConfig.removeAdConfigDescription:
Delete an existing Active Directory configuration.
Precondition:
Right 🔓 change global config of the Provider Customer required.
Postcondition:
Active Directory configuration is removed.
Further Information:
None.
-
systemAuthConfig.removeOAuthClientDescription:
Delete an existing OAuth client.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
OAuth client is removed.
Further Information:
None.
-
systemAuthConfig.removeOpenIdIdpConfigDescription:
Delete an existing OpenID Connect IDP configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
OpenID Connect IDP configuration is removed.
Further Information:
None.
-
systemAuthConfig.removeRadiusConfigDescription:
Delete existing RADIUS configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
RADIUS configuration is deleted.
Further Information:
None.
-
systemAuthConfig.requestAdConfigDescription:
Retrieve the configuration of an Active Directory.
Precondition:
Right 🔓 read global config of the Provider Customer required.
Postcondition:
Active Directory configuration is returned.
Further Information:
None.
-
systemAuthConfig.requestAdConfigsDescription:
Retrieve a list of configured Active Directories.
Precondition:
Right 🔓 read global config of the Provider Customer required.
Postcondition:
List of Active Directory configurations is returned.
Further Information:
None.
-
systemAuthConfig.requestOAuthClientDescription:
Retrieve the configuration of an OAuth client.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
OAuth client is returned.
Further Information:
None.
-
systemAuthConfig.requestOAuthClientsDescription:
Retrieve a list of configured OAuth clients.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
List of OAuth clients is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
isStandard:eq:true
Get standard OAuth clients.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
clientName:desc|isStandard:asc
Sort byclientNamedescending ANDisStandardascending.Sorting options:
Expand
-
systemAuthConfig.requestOpenIdIdpConfigDescription:
Retrieve an OpenID Connect IDP configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
OpenID Connect IDP configuration is returned.
Further Information:
None.
-
systemAuthConfig.requestOpenIdIdpConfigsDescription:
Retrieve a list of configured OpenID Connect IDPs.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
List of OpenID Connect IDP configurations is returned.
Further Information:
None.
-
systemAuthConfig.requestRadiusConfigDescription:
Retrieve a RADIUS configuration.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
RADIUS configuration is returned.
Further Information:
None.
-
systemAuthConfig.testAdConfigDescription:
Test Active Directory configuration.
Precondition:
Right 🔓 change global config of the Provider Customer required.
Postcondition:
Active Directory configuration is returned if successful.
Further Information:
DRACOON tries to establish a connection with the provided information.
-
systemAuthConfig.testRadiusConfigDescription:
Test RADIUS configuration.
Precondition:
Right 🔓 read global config of the Provider Customer required.
Postcondition:
RADIUS configuration is returned if successful.
Further Information:
DRACOON tries to establish a connection with the provided information.
-
systemAuthConfig.updateAdConfigDescription:
Update an existing Active Directory configuration.
Precondition:
Right 🔓 change global config of the Provider Customer required.
Postcondition:
Active Directory configuration updated.
Further Information:
None.
-
systemAuthConfig.updateOAuthClientDescription:
Update an existing OAuth client.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
OAuth client updated.
Further Information:
Client secret MUST have:
- at least 12 characters, at most 32 characters
- only lower case characters, upper case characters and digits
- at least 1 lower case character, 1 upper case character and 1 digit
The client secret is optional and will be generated if it is left empty.
Valid grant types are:
authorization_codeimplicitpasswordclient_credentialsrefresh_token
Grant type
client_credentialsis currently NOT permitted!If grant types
authorization_codeorimplicitare used, a redirect URI MUST be provided! -
systemAuthConfig.updateOpenIdIdpConfigDescription:
Update an existing OpenID Connect IDP configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
OpenID Connect IDP configuration is updated.
Further Information:
None.
-
systemAuthConfig.updateRadiusConfigDescription:
Update existing RADIUS configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
RADIUS configuration is updated.
Further Information:
None.
-
systemPoliciesConfig.changeClassificationPoliciesConfig🚀 Since v4.30.0
Description:
Change current classification policies:
shareClassificationPolicies
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Classification policies are changed.
Further Information:
classificationRequiresSharePassword: When a node has this classification or higher, it cannot be shared without a password. If the node is an encrypted file this policy has no effect.0means no password will be enforced. -
systemPoliciesConfig.changeGuestUsersPoliciesConfig🚀 Since v4.40.0
Description:
Change current guest user policies.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Guest user policies are changed.
Further Information:
None.
-
systemPoliciesConfig.changeMfaPoliciesConfig🚀 Since v4.37.0
Description:
Change current multi-factor authentication policies.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Multi-factor authentication policies are changed.
Further Information:
None.
-
systemPoliciesConfig.changePasswordPoliciesConfig🚀 Since v4.14.0
Description:
Change current password policies for any password types:
loginsharesencryption
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Password policies get changed.
Further Information:
None.
Available password policies:
Expand
Deprecated password policies:
Expand
mustContainCharactersmatrix:Expand
-
systemPoliciesConfig.enforceLoginPasswordChange🚀 Since v4.24.0
Description:
Enforce login password change for all users.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Login password change is enforced. Every user has to change their login password at next login.
Further Information:
None.
-
systemPoliciesConfig.requestClassificationPoliciesConfig🚀 Since v4.30.0
Description:
Retrieve a list of classification policies:
shareClassificationPolicies
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
List of configured classification policies is returned.
Further Information:
classificationRequiresSharePassword: When a node has this classification or higher, it cannot be shared without a password. If the node is an encrypted file this policy has no effect.0means no password will be enforced. -
systemPoliciesConfig.requestGuestUsersPoliciesConfig🚀 Since v4.40.0
Description:
Retrieve guest user policies.
Precondition:
Right 🔓 read global config of the Provider Customer required.
Postcondition:
Guest user policies are returned.
Further Information:
None.
-
systemPoliciesConfig.requestMfaPoliciesConfig🚀 Since v4.37.0
Description:
Retrieve a list of multi-factor authentication policies.
Precondition:
Right 🔓 read global config of the Provider Customer required.
Postcondition:
List of configured multi-factor authentication policies is returned.
Further Information:
None.
-
systemPoliciesConfig.requestPasswordPoliciesConfig🚀 Since v4.14.0
Description:
Retrieve a list of configured password policies for all password types:
loginsharesencryption
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
List of configured password policies is returned.
Further Information:
None.
Available password policies:
Expand
-
systemPoliciesConfig.requestPasswordPoliciesForPasswordType🚀 Since v4.14.0
Description:
Retrieve a list of configured password policies for a certain password type:
loginsharesencryption
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
List of configured password policies is returned.
Further Information:
None.
Available password policies:
Expand
-
systemSettingsConfig.requestAuthConfig🚀 Since v4.6.0
Description:
DRACOON authentication configuration entry point.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Returns a list of configurable authentication methods.
Further Information:
Authentication methods are sorted by priority attribute.
Smaller values have higher priority.
Authentication method with highest priority is considered as default.
Priority MUST be a positive value.Configurable authentication settings:
Expand
-
systemSettingsConfig.requestEventlogConfig🚀 Since v4.6.0
Description:
DRACOON eventlog configuration entry point.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Returns a list of configurable eventlog settings.
Further Information:
None.
Configurable eventlog settings:
Expand
-
systemSettingsConfig.requestGeneralSettings🚀 Since v4.6.0
Description:
DRACOON general settings configuration entry point.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Returns a list of configurable general settings.
Further Information:
Auth token restrictions:
A restriction is a lower bound for a token timeout and defines a duration after which a token is invalidated when it wasn't used.
The access/refresh token validity duration of the client is the upper bound. A token is invalidated - in any case - when it has passed.Auth token restrictions are enabled by default.
- Default access token validity: 2 hours
- Default refresh token validity: 30 days
Configurable general settings:
Expand
Deprecated configurable general settings:
Expand
-
systemSettingsConfig.requestInfrastructureProperties🚀 Since v4.6.0
Description:
DRACOON infrastructure properties entry point.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Returns a list of read-only infrastructure properties.
Further Information:
Source:
core-service.propertiesRead-only infrastructure properties:
Expand
-
systemSettingsConfig.requestSyslogConfig🚀 Since v4.6.0
Description:
DRACOON syslog configuration entry point.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Returns a list of configurable syslog settings.
Further Information:
None.
Configurable syslog settings:
Expand
-
systemSettingsConfig.requestSystemDefaults🚀 Since v4.6.0
Description:
DRACOON system defaults configuration entry point.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
Returns a list of configurable system default values.
Further Information:
None.
Configurable default values
Expand
-
systemSettingsConfig.updateAuthConfig🚀 Since v4.6.0
Description:
DRACOON authentication configuration entry point.
Change configurable authentication settings.Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
One or more authentication methods gets changed.
Further Information:
Authentication methods are sorted by priority attribute.
Smaller values have higher priority.
Authentication method with highest priority is considered as default.
Priority MUST be a positive value.Configurable authentication settings:
Expand
-
systemSettingsConfig.updateEventlogConfig🚀 Since v4.6.0
Description:
DRACOON eventlog configuration entry point.
Change configurable eventlog settings.Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
One or more eventlog settings gets changed.
Further Information:
None.
Configurable eventlog settings:
Expand
-
systemSettingsConfig.updateGeneralSettings🚀 Since v4.6.0
Description:
DRACOON general settings configuration entry point.
Change configurable general settings.Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
One or more general settings gets changed.
Further Information:
Auth token restrictions are enabled by default.
- Default access token validity: 2 hours
- Default refresh token validity: 30 days
Configurable general settings:
Expand
Deprecated configurable general settings:
Expand
-
systemSettingsConfig.updateSyslogConfig🚀 Since v4.6.0
Description:
DRACOON syslog configuration entry point.
Change configurable syslog settings.Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
One or more syslog settings gets changed.
Further Information:
None.
Configurable syslog settings:
Expand
-
systemSettingsConfig.updateSystemDefaults🚀 Since v4.6.0
Description:
DRACOON system defaults configuration entry point.
Change configurable system default values.Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
One or more system default values gets changed.
Further Information:
None.
Configurable default values
Expand
-
systemStorageConfig.createS3Config🚀 Since v4.3.0
Description:
Create new S3 configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
New S3 configuration is created.
Further Information:
Forbidden characters in bucket names: [
.]
bucketNameandendpointUrlare deprecated, usebucketUrlinstead.Virtual hosted style access
Example: https://bucket-name.s3.region.amazonaws.com/key-name
-
systemStorageConfig.createS3Tag🚀 Since v4.9.0
Description:
Create new S3 tag.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
New S3 tag is created.
Further Information:
- Maximum key length: 128 characters.
- Maximum value length: 256 characters.
- Both S3 tag key and value are case-sensitive strings.
- Maximum of 20 mandatory S3 tags is allowed.
-
systemStorageConfig.removeS3Tag🚀 Since v4.9.0
Description:
Delete S3 tag.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
S3 tag gets deleted.
Further Information:
None.
-
systemStorageConfig.request3Config🚀 Since v4.3.0
Description:
Retrieve S3 configuration.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
S3 configuration is returned.
Further Information:
None.
Virtual hosted style access
Example: https://bucket-name.s3.region.amazonaws.com/key-name
-
systemStorageConfig.requestS3Tag🚀 Since v4.9.0
Description:
Retrieve single S3 tag.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
S3 tag is returned.
Further Information:
None.
-
systemStorageConfig.requestS3TagList🚀 Since v4.9.0
Description:
Retrieve all configured S3 tags.
Precondition:
Right 🔓 read global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
S3 tags are returned.
Further Information:
An empty list is returned if no S3 tags are found / configured.
-
systemStorageConfig.updateS3Config🚀 Since v4.3.0
Description:
Update existing S3 configuration.
Precondition:
Right 🔓 change global config and role 👤 Config Manager of the Provider Customer required.
Postcondition:
S3 configuration is updated.
Further Information:
Forbidden characters in bucket names: [
.]
bucketNameandendpointUrlare deprecated, usebucketUrlinstead.Virtual hosted style access
Example: https://bucket-name.s3.region.amazonaws.com/key-name
-
uploads.cancelFileUploadByTokenDescription:
Cancel file upload.
Precondition:
Valid upload token.
Postcondition:
Upload canceled, token invalidated and all already transfered chunks removed.
Further Information:
It is recommended to notify the API about cancelled uploads if possible.
-
uploads.completeFileUploadByTokenDescription:
Finish uploading a file.
Precondition:
Valid upload token.
Postcondition:
File created.
Further Information:
The provided file name might be changed in accordance with the resolution strategy:
- autorename: changes the file name and adds a number to avoid conflicts.
- overwrite: deletes any old file with the same file name.
- fail: returns an error; in this case, another
PUTrequest with a different file name may be sent.
Please ensure that all chunks have been transferred correctly before finishing the upload.
Download share id (if exists) gets changed if:
- node with the same name exists in the target container
resolutionStrategyisoverwritekeepShareLinksistrue
-
uploads.uploadFileByTokenAsMultipart1Description:
Upload a (chunk of a) file.
Precondition:
Valid upload token.
Postcondition:
Chunk uploaded.
Further Information:
Range requests are supported.
Following
Content-Typesare supported by this API:multipart/form-data- provided
Content-Type
For both file upload types set the correct
Content-Typeheader and body.Examples:
multipart/form-data
- any other
Content-Type
POST /api/v4/uploads/{token} HTTP/1.1 Header:...Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW... Body:------WebKitFormBoundary7MA4YWxkTrZu0gWContent-Disposition: form-data; name="file"; filename="file.txt"Content-Type: text/plain Content of file.txt------WebKitFormBoundary7MA4YWxkTrZu0gW--POST /api/v4/uploads/{token} HTTP/1.1 Header:...Content-Type: { ... }... Body:raw content -
user.changeUserPasswordDescription:
Change the user's password.
Precondition:
Authenticated user.
Postcondition:
User's password is changed.
Further Information:
The password MUST comply to configured password policies.
Forbidden characters in passwords: [
&,',<,>] -
user.confirmTotpSetup🚀 Since v4.37.0
Description:
Confirm second factor TOTP setup with a generated OTP.
Precondition:
Authenticated user
Postcondition:
Second factor TOTP is enabled.
Further Information:
None.
-
user.createAndPreserveUserKeyPair🚀 Since v4.24.0
Description:
Create user key pair and preserve copy of old private key.
Precondition:
Authenticated user.
Postcondition:
Key pair is created.
Copy of old private key is preserved.Further Information:
You can submit your old private key, encrypted with your current password.
This allows migrating file keys encrypted with your old key pair to the new one. -
user.deleteMfaTotpSetup🚀 Since v4.37.0
Description:
Delete multi-factor authentication TOTP setup with a valid OTP code.
Precondition:
Authenticated user
Multi-factor authentication is NOT enforcedPostcondition:
Second factor TOTP is disabled.
Further Information:
None.
-
user.enableCustomerEncryption🚧 Deprecated since v4.24.0
Use
POST /settings/keypairAPIDescription:
Activate client-side encryption for according customer.
Precondition:
Right 🔓 change config required.
Postcondition:
Client-side encryption is enabled.
Further Information:
Sets the ability for this customer to encrypt rooms.
Once enabled on customer level, it CANNOT be unset.
On activation, a customer rescue key pair MUST be set. -
user.getMfaStatusForUser🚀 Since v4.37.0
Description:
Request information about the user's mfa status
Precondition:
Authenticated user.
Postcondition:
None.
Further Information:
None.
-
user.getTotpSetupInformation🚀 Since v4.37.0
Description:
Get setup information for multi-factor authentication (TOTP).
Precondition:
Authenticated user.
Postcondition:
None.
Further Information:
None.
-
user.listDownloadShareSubscriptions🚀 Since v4.20.0
Description:
Retrieve a list of subscribed Download Shares for current user.
Precondition:
Authenticated user.
Postcondition:
List of subscribed Download Shares is returned.
Further Information:
None.
Filtering
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
authParentId:eq:#
Get download shares whereauthParentIdequals#.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
downloadShareId:desc|authParentId:asc
Sort bydownloadShareIddescending ANDauthParentIdascending.Sorting options:
Expand
-
user.listNodeSubscriptions🚀 Since v4.20.0
Description:
Retrieve a list of subscribed nodes for current user.
Precondition:
Authenticated user.
Postcondition:
List of subscribed nodes is returned.
Further Information:
None.
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
authParentId:eq:#
Get nodes whereauthParentIdequals#.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
nodeId:desc|authParentId:asc
Sort bynodeIddescending ANDauthParentIdascending.Sorting options:
Expand
-
user.listUploadShareSubscriptions🚀 Since v4.24.0
Description:
Retrieve a list of subscribed Upload Shares for current user.
Precondition:
Authenticated user.
Postcondition:
List of subscribed Upload Shares is returned.
Further Information:
None.
Filtering
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
targetNodeId:eq:#
Get upload shares wheretargetNodeIdequals#.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
uploadShareId:desc|targetNodeId:asc
Sort byuploadShareIddescending ANDtargetNodeIdascending.Sorting options:
Expand
-
user.logout🚧 Deprecated since v4.12.0
Description:
Log out a user.
Precondition:
Authenticated user.
Postcondition:
- User is logged out
- Authentication token gets invalidated.
Further Information:
None.
-
user.pingUserDescription:
Test connection to DRACOON Server (while authenticated).
Precondition:
Authenticated user.
Postcondition:
200 OKwith principal information is returned if successful.Further Information:
None.
-
user.removeOAuthApproval🚀 Since v4.22.0
Functional Description:
Delete an OAuth client approval.
Precondition:
Authenticated user and valid client ID
Postcondition:
OAuth Client approval is revoked.
Further Information:
None.
-
user.removeOAuthAuthorization🚀 Since v4.12.0
Description:
Delete an authorization.
Precondition:
Authenticated user and valid client ID, authorization ID
Postcondition:
Authorization is revoked.
Further Information:
None.
-
user.removeOAuthAuthorizationsDescription:
Delete all authorizations of a client.
Precondition:
Authenticated user and valid client ID
Postcondition:
All authorizations for the client are revoked.
Further Information:
None.
-
user.removeProfileAttribute🚀 Since v4.7.0
Description:
Delete custom user profile attribute.
Precondition:
None.
Postcondition:
Custom user profile attribute is deleted.
Further Information:
Allowed characters for keys are:
[a-zA-Z0-9_-] -
user.removeUserKeyPairDescription:
Delete user key pair.
Precondition:
Authenticated user.
Postcondition:
Key pair is deleted.
Further Information:
If parameter
versionis not set and two key versions exist, this API deletes version A.
If two keys with the same version are set, this API deletes the older one.This will also remove all file keys that were encrypted with the user public key. If the user had exclusive access to some files, those are removed as well since decrypting them became impossible.
-
user.requestAvatar🚀 Since v4.11.0
Description:
Get the avatar.
Precondition:
Authenticated user.
Postcondition:
Avatar is returned.
Further Information:
None.
-
user.requestCustomerInfoDescription:
Use this API to get:
- customer name
- used / free space
- used / available
- user account info
of the according customer.
Precondition:
Authenticated user.
Postcondition:
Customer information is returned.
Further Information:
None.
-
user.requestCustomerKeyPair🚧 Deprecated since v4.24.0
Use
GET /settings/keypairAPIDescription:
Retrieve the customer rescue key pair.
Precondition:
Authenticated user.
Postcondition:
Key pair is returned.
Further Information:
The private key is password-based encrypted with
AES256/PBKDF2. -
user.requestListOfNotificationConfigs🚀 Since v4.20.0
Description:
Retrieve a list of notification configurations for current user.
Precondition:
Authenticated user.
Postcondition:
List of available notification configurations is returned.
Further Information:
None.
-
user.requestOAuthApprovals🚀 Since v4.22.0
Functional Description:
Retrieve information about all OAuth client approvals.
Precondition:
Authenticated user.
Postcondition:
None.
Further Information:
None.
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
clientName:desc
Sort byclientNamedescending.Sorting options:
Expand
-
user.requestOAuthAuthorizationsDescription:
Retrieve information about all OAuth client authorizations.
Precondition:
Authenticated user.
Postcondition:
List of OAuth client authorizations is returned.
Further Information:
Filtering:
Filter string syntax:
FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
isStandard:eq:true
Get standard OAuth clients.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.Example
clientName:desc
Sort byclientNamedescending.Sorting options:
Expand
-
user.requestProfileAttributes🚀 Since v4.7.0
Description:
Retrieve a list of user profile attributes.
Precondition:
None.
Postcondition:
List of attributes is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
key:cn:searchString_1|value:cn:searchString_2
Filter by attribute key containssearchString_1AND attribute value containssearchString_2.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
key:asc|value:desc
Sort bykeyascending AND byvaluedescending.Sorting options:
Expand
-
user.requestUserInfoDescription:
Retrieves all information regarding the current user's account.
Precondition:
Authenticated user.
Postcondition:
User information is returned.
Further Information:
Setting the query parameter
more_infototrue, causes the API to return more details e.g. the user's groups.customer(CustomerData) attribute inUserAccountresponse model is deprecated. Please use response fromGET /user/account/customerinstead. -
user.requestUserKeyPairDescription:
Retrieve the user key pair.
Precondition:
Authenticated user.
Postcondition:
Key pair is returned.
Further Information:
The private key is password-based encrypted with
AES256/PBKDF2. -
user.requestUserKeyPairs🚀 Since v4.24.0
Description:
Retrieve all user key pairs to allow re-encrypting file keys without need for a second distributor.
Precondition:
Authenticated user.
Postcondition:
List of key pairs is returned.
Further Information:
None.
-
user.resetAvatar🚀 Since v4.11.0
Description:
Reset (custom) avatar to default avatar.
Precondition:
Authenticated user.
Postcondition:
- User's avatar gets deleted.
- Default avatar is set.
Further Information:
None.
-
user.setProfileAttributes🚧 Deprecated since v4.12.0
Description:
Set custom user profile attributes.
Precondition:
None.
Postcondition:
Custom user profile attributes are set.
Further Information:
Batch function.
All existing user profile attributes will be deleted.- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive
- Maximum key length is 255
- Maximum value length is 4096
- Allowed characters for keys are:
-
user.setUserKeyPairDescription:
Set the user key pair.
Precondition:
Authenticated user.
Postcondition:
Key pair is set.
Further Information:
Overwriting an existing key pair is NOT possible.
Please delete the existing key pair first.
The private key is password-based encrypted withAES256/PBKDF2. -
user.subscribeDownloadShare🚀 Since v4.20.0
Description:
Subscribe Download Share for notifications.
Precondition:
User with "manage download share" permissions on target node.
Postcondition:
Download Share is subscribed.
Notifications for this Download Share will be triggered in the future.Further Information:
None.
-
user.subscribeDownloadShares🚀 Since v4.25.0
Description:
Subscribe/Unsubscribe download shares for notifications.
Precondition:
User with "manage download share" permissions on target node.
Postcondition:
Download shares are subscribed or unsubscribed. Notifications for these download shares will be triggered in the future.
Further Information:
Maximum number of subscriptions is 200.
-
user.subscribeNode🚀 Since v4.20.0
Description:
Subscribe node for notifications.
Precondition:
User has "read" permissions in auth parent room.
Postcondition:
Node is subscribed. Notifications for this node will be triggered in the future.
Further Information:
None.
-
user.subscribeUploadShare🚀 Since v4.24.0
Description:
Subscribe Upload Share for notifications.
Precondition:
User with "manage upload share" permissions on target node.
Postcondition:
Upload Share is subscribed.
Notifications for this Upload Share will be triggered in the future.Further Information:
None.
-
user.subscribeUploadShares🚀 Since v4.25.0
Description:
Subscribe/Unsubscribe upload shares for notifications.
Precondition:
User with "manage upload share" permissions on target node.
Postcondition:
Upload shares are subscribed or unsubscribed. Notifications for these upload shares will be triggered in the future.
Further Information:
Maximum number of subscriptions is 200.
-
user.unsubscribeDownloadShare🚀 Since v4.20.0
Description:
Unsubscribe Download Share from notifications.
Precondition:
User with "manage download share" permissions on target node.
Postcondition:
Download Share is unsubscribed.
Notifications for this Download Share are disabled.Further Information:
None.
-
user.unsubscribeNode🚀 Since v4.20.0
Description:
Unsubscribe node from notifications.
Precondition:
User has "read" permissions in auth parent room.
Postcondition:
Node is unsubscribed.
Notifications for this node are disabled.Further Information:
None.
-
user.unsubscribeUploadShare🚀 Since v4.24.0
Description:
Unsubscribe Upload Share from notifications.
Precondition:
User with "manage upload share" permissions on target node.
Postcondition:
Upload Share is unsubscribed.
Notifications for this Upload Share are disabled.Further Information:
None.
-
user.updateNodeSubscriptions🚀 Since v4.25.0
Description:
Subscribe/Unsubscribe nodes for notifications.
Precondition:
User has "read" permissions in auth parent room.
Postcondition:
Nodes are subscribed or unsubscribed. Notifications for these nodes will be triggered in the future.
Further Information:
Maximum number of subscriptions is 200.
-
user.updateNotificationConfig🚀 Since v4.20.0
Description:
Update notification configuration for current user.
Precondition:
Authenticated user.
Postcondition:
Notification configuration is updated.
Further Information:
Leave
channelIdsempty to disable notifications. -
user.updateProfileAttributes🚀 Since v4.7.0
Description:
Add or edit custom user profile attributes.
🚧 Warning: Please note that the response with HTTP status code 200 (OK) is deprecated and will be replaced with HTTP status code 204 (No content)!Precondition:
None.
Postcondition:
Custom user profile attributes are added or edited.
Further Information:
Batch function.
If an entry existed before, it will be overwritten.
Range submodel is never returned.- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive
- Maximum key length is 255
- Maximum value length is 4096
- Allowed characters for keys are:
-
user.updateUserAccountDescription:
Update current user's account.
Precondition:
Authenticated user.
Postcondition:
User's account is updated.
Further Information:
- All input fields are limited to 150 characters.
- All characters are allowed.
customer(CustomerData) attribute inUserAccountresponse model is deprecated. Please use response fromGET /user/account/customerinstead. -
user.uploadAvatarAsMultipart🚀 Since v4.11.0
Description:
Change the avatar.
Precondition:
Authenticated user.
Postcondition:
Avatar is changed.
Further Information:
- Media type MUST be
jpegorpng - File size MUST bei less than
5 MB - Dimensions MUST be
256x256 px
- Media type MUST be
-
user.useEmergencyCode🚀 Since v4.37.0
Description:
Using emergency code for login
Precondition:
User has MFA enabled and is already logged in with account/pw (aka pre-Auth-Role)
Postcondition:
All MFA-setups for the user are deleted.
Further Information:
-
users.createUserDescription:
Create a new user.
Precondition:
Right 🔓 change users required.
Postcondition:
New user is created.
Further Information:
- If a user should NOT expire, leave
expireAtempty. - All input fields are limited to 150 characters
- Forbidden characters in first or last name: [
<,>] - Forbidden characters in passwords: [
&,',<,>]
Authentication Method Options:
Expand
- If a user should NOT expire, leave
-
users.removeUserDescription:
Delete a user.
Precondition:
Right 🔓 delete users required.
Postcondition:
User is deleted.
Further Information:
User CANNOT be deleted if he is a last room administrator of any room.
-
users.removeUserAttributeDescription:
Delete custom user attribute.
Precondition:
Right 🔓 change users required.
Postcondition:
Custom user attribute is deleted.
Further Information:
- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive.
- Allowed characters for keys are:
-
users.requestEmergencyMfaCode🚀 Since v4.37.0
Description:
Request emergency MFA code for a specific user.
Precondition:
Right 🔓 change users required.
Postcondition:
Emergency MFA code is returned.
Further Information:
Emergency code can be used instead of standard MFA authentication to disable all MFA setups.
-
users.requestLastAdminRoomsUsers🚀 Since v4.10.0
Description:
Retrieve a list of all rooms where the user is last admin (except homeroom and its subordinary rooms).
Precondition:
Right 🔓 change users required.
Postcondition:
List of rooms is returned.
Further Information:
An empty list is returned if no rooms were found where the user is last admin.
-
users.requestUserDescription:
Retrieve detailed information about a single user.
Precondition:
Right 🔓 read users required.
Postcondition:
User information is returned.
Further Information:
None.
Authentication Method Options:
Expand
-
users.requestUserAttributes🚀 Since v4.12.0
Description:
Retrieve a list of user attributes.
Precondition:
None.
Postcondition:
List of attributes is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
key:cn:searchString_1|value:cn:searchString_2
Filter by attribute key containssearchString_1AND attribute value containssearchString_2.Filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
key:asc|value:desc
Sort bykeyascending AND byvaluedescending.Sorting options:
Expand
-
users.requestUserGroupsDescription:
Retrieves a list of groups a user is member of and / or can become a member.
Precondition:
Right 🔓 read users required.
Postcondition:
List of groups is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isMember:eq:false|name:cn:searchString
Get all groups that the user is NOT member of AND whose name is likesearchString.Filtering options:
Expand
-
users.requestUserRolesDescription:
Retrieve a list of all roles granted to a user.
Precondition:
Right 🔓 read users required.
Postcondition:
List of granted roles is returned.
Further Information:
None.
-
users.requestUsersDescription:
Returns a list of DRACOON users.
Precondition:
Right 🔓 read users required.
Postcondition:
List of users is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Except forlogin,firstNameandlastName- these are connected via logical disjunction (OR)
Filter string syntax:FIELD_NAME:OPERATOR:VALUE[:VALUE...]Example
login:cn:searchString_1|firstName:cn:searchString_2|lockStatus:eq:2
Filter users by login containssearchString_1OR firstName containssearchString_2AND those who are NOT locked.Filtering options:
Expand
Deprecated filtering options:
Expand
Sorting:
Sort string syntax:
FIELD_NAME:ORDER
ORDERcan beascordesc.
Multiple sort fields are supported.Example
firstName:asc|lastLoginSuccessAt:desc
Sort byfirstNameascending AND bylastLoginSuccessAtdescending.Sorting options:
Expand
Deprecated sorting options:
Expand
-
users.requestUsersRooms🚧 Deprecated since v4.10.0
Description:
Retrieves a list of rooms granted to the user and / or that can be granted.
Precondition:
Right 🔓 read users required.
Postcondition:
List of rooms is returned.
Further Information:
Filtering:
All filter fields are connected via logical conjunction (AND)
Filter string syntax:FIELD_NAME:OPERATOR:VALUEExample
isGranted:eq:true|isLastAdmin:eq:true|name:cn:searchString
Get all rooms that the user is granted AND is last admin AND whose name is likesearchString.Filtering options:
Expand
-
users.setUserAttributes🚧 Deprecated since v4.28.0
Description:
Set custom user attributes.
Precondition:
Right 🔓 change users required.
Postcondition:
Custom user attributes are set.
Further Information:
Batch function.
All existing user attributes will be deleted.- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive.
- Allowed characters for keys are:
-
users.updateUserDescription:
Update user's metadata.
Precondition:
Right 🔓 change users required.
Postcondition:
User's metadata is updated.
Further Information:
- If a user should NOT expire, leave
expireAtempty. - All input fields are limited to 150 characters
- All characters are allowed.
Authentication Method Options:
Expand
- If a user should NOT expire, leave
-
users.updateUserAttributesDescription:
Add or edit custom user attributes.
🚧 Warning: Please note that the response with HTTP status code 200 (OK) is deprecated and will be replaced with HTTP status code 204 (No content)!Precondition:
Right 🔓 change users required.
Postcondition:
Custom user attributes gets added or edited.
Further Information:
Batch function.
If an entry exists before, it will be overwritten.- Allowed characters for keys are:
[a-zA-Z0-9_-] - Characters are case-insensitive.
- Allowed characters for keys are:
-
openapi.previewSpecPreview an OpenAPI document before adding it as a source
-
openapi.addSourceAdd an OpenAPI source and register its operations as tools