SOFiE
API docs by Redocly

SOFiE HTTP API (2.0.0)

Download OpenAPI specification:

The SOFiE HTTP API is used by third‑party applications to manage packages and users in the SOFiE application. All functions run from the perspective of an existing user or application administrator.

The API is described using OpenAPI 3.1. The current specification in YAML format can be downloaded here.

The base path for all calls is /api/v2/user.

Access requires an API token created in the application administration. Send the token in every request in the HTTP Authorization header as a Bearer token:

Authorization: Bearer <token>

The API token is linked to a specific user or administrator.

If the API token is linked to an administrator, you can specify the user under which operations should be performed using the X-Sofie-Impersonate-UserId or X-Sofie-Impersonate-Username header. Only one of these headers can be used in a single request:

X-Sofie-Impersonate-UserId: 1b31dd01-c272-4025-94a8-7bd1da484b22
// or
X-Sofie-Impersonate-Username: document-exchange

Some API operations can only be performed by a regular user or only by an administrator. For some operations, the availability of specific attributes depends on the user type. Conditions and differences are always described for individual operations.

The HTTP header Content-Type must be set to application/json in each request:

Content-Type: application/json

All time data use the "date-time" format according to RFC 3339.

If a request is denied, the reason is typically stated in the X-Sofie-Response-Reason header (for example, limit exceeded, missing package password, and so on).

Data filtering

In calls that return a list of items, it is mostly possible to limit the set of returned records using a user-defined filter.

This filter is in JSON format and is based on the JsonLogic language. Supported operators and attributes are listed for each operation. Operators !, and and or are always supported.

The API generally supports these operators:

  • !: negation of the enclosed expression, for example:

    {"!": {"==": [{"var":"name"}, "Project X"]} }

  • and: conjunction, for example:

    {"and":[ {"contains": [{"var":"workflowState"}, "ACTIVE"]}, {"contains": [{"var":"checkState"}, "CLEAN"]} ]}

  • or: disjunction, for example:

    {"or":[ {"==": [{"var":"name"}, "Project X"]}, {"==": [{"var":"name"}, "Project Y"]} ]}

  • ==: equality, for example:

    {"==":[{"var":"name"},"Project X"]}

  • contains: case-sensitive substring search, for example:

    {"contains":[{"var":"name"},"Project"]}

  • icontains: case-insensitive substring search, for example:

    {"icontains":[{"var":"name"},"project"]}

  • in: search for an element in an array, for example:

    {"in":["task:done",{"var":"tags"}]}

The filter is sent within the request in the URL parameter $filter, e.g.:

/packages/inbox?$filter={"eq": [{"var": "name"}, "Project summary"]}

Uploading a new package

The procedure for uploading a new package is as follows:

  1. A POST request to the path /packages creates a new empty package. The response contains a unique package ID (packageId) and a unique root folder ID (rootFolderId).
  2. In the created package, it is possible to create additional folders if necessary by sending a POST request to the path /packages/{packageId}/folders.
  3. Files are uploaded in multiple steps:
    1. First, a file record is created using a POST request to the path /packages/{packageId}/folders/{folderId}/files; the response returns a unique file ID (fileId)
    2. Then, the file content is uploaded by making a PUT call to the path /packages/{packageId}/files/{fileId}/content
    3. Finally, the completion of the file content upload is confirmed by calling PATCH on the path /packages/{packageId}/files/{fileId}/state

Package management

Operations for package management.

Creates a new package

Creates a new package on the server including the root folder and returns the package ID and root folder ID. The package is in the active state after creation.

Only a regular user can call this operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required

Definition of package attributes

name
string <= 100 characters

Package name

note
string <= 10000 characters

Note

downloadPassword
string <= 30 characters

Password for downloading the package

encryptDataWithPassword
boolean
Default: false

Encryption of package data with a password for download

downloadExpiration
integer

Validity of the package (in days)

persistent
boolean
Default: false

Persistent package (with unlimited validity)

This attribute is available only to users with the appropriate permission or to the administrator.

accessType
required
string
Enum: "PUBLIC" "PRIVATE" "INTERNAL"

Accessibility of the package.

Possible values:

  • PUBLIC - public
  • PRIVATE - private
  • INTERNAL - internal
Array of objects (Recipient)

Recipients of the package

limitAccessCount
number

Maximum number of accesses to the package

sendEmailNotifications
boolean
Default: true

Whether to send email notifications to recipients when the package is created.

Available since version 2.5.0.

Responses

Request samples

Content type
application/json
{
  • "name": "Photo documentation of the object",
  • "note": "Photographed with a mobile phone",
  • "downloadPassword": "password123",
  • "encryptDataWithPassword": "false",
  • "downloadExpiration": "7",
  • "persistent": "true",
  • "accessType": "PUBLIC",
  • "recipients": [],
  • "limitAccessCount": "10",
  • "sendEmailNotifications": "false"
}

Response samples

Content type
application/json
{
  • "packageId": "28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4",
  • "rootFolderId": "b4148092-ddcf-417c-8c91-64848521ca15"
}

Returns a list of received packages

Returns a list of packages received by the user.

Without specifying the parameter $top, 100 records are returned; the maximum value of the parameter $top and thus the number of returned records is 5000.

The following operators and attributes are supported for the URL parameter $filter (see the Data filtering section):

  • ==: name, workflowState, checkState
  • contains: name
  • icontains: name
  • in: tags, workflowState, checkState

Example of a filter (the name must be "Project summary" and the tags must include the tag "done"):

{
  "and": [
    {
      "==": [
        {
          "var": "name"
        },
        "Project summary"
      ]
    },
    {
      "in": [
        "done",
        {
          "var": "tags"
        }
      ]
    }
  ]
}

Example in compact form:

{"and":[{"==":[{"var":"name"},"Project summary"]},{"in":["done",{"var":"tags"}]}]}

Only a regular user can call this operation.

Authorizations:
bearerAuth
query Parameters
$top
integer
Example: $top=100

The maximum number of records to be returned (usable for pagination).

$skip
integer
Example: $skip=100

Number of records to be skipped (applicable for pagination).

$filter
string
Example: $filter={"and":[{"==":[{"var":"name"},"Project summary"]},{"in":["done",{"var":"tags"}]}]}

JSON filter expression in JsonLogic format (sent as a URL‑encoded string). Supported operators and attributes are listed for each operation.

Responses

Response samples

Content type
application/json
{
  • "count": "100",
  • "total": "5660",
  • "data": [
    ]
}

Returns a list of sent packages

Returns a list of packages sent by the user.

Without specifying the parameter $top, 100 records are returned; the maximum value of the parameter $top and thus the number of returned records is 5000.

The following operators and attributes are supported for the URL parameter $filter (see the Data filtering section):

  • ==: name, workflowState, checkState
  • contains: name
  • icontains: name
  • in: tags, workflowState, checkState

Example of a filter (the name must be "Project summary" and the tags must include the tag "done"):

{
  "and": [
    {
      "==": [
        {
          "var": "name"
        },
        "Project summary"
      ]
    },
    {
      "in": [
        "done",
        {
          "var": "tags"
        }
      ]
    }
  ]
}

Example in compact form:

{"and":[{"==":[{"var":"name"},"Project summary"]},{"in":["done",{"var":"tags"}]}]}

Only a regular user can call this operation.

Authorizations:
bearerAuth
query Parameters
$top
integer
Example: $top=100

The maximum number of records to be returned (usable for pagination).

$skip
integer
Example: $skip=100

Number of records to be skipped (applicable for pagination).

$filter
string
Example: $filter={"and":[{"==":[{"var":"name"},"Project summary"]},{"in":["done",{"var":"tags"}]}]}

JSON filter expression in JsonLogic format (sent as a URL‑encoded string). Supported operators and attributes are listed for each operation.

Responses

Response samples

Content type
application/json
{
  • "count": "100",
  • "total": "5660",
  • "data": [
    ]
}

Returns information about the package

Returns detailed information about the package packageId.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Download-Password
string <= 100 characters
Example: password123

Password for downloading the package (if package download is password-protected)

X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Response samples

Content type
application/json
{
  • "workflowState": "ACTIVE",
  • "checkState": "QUARANTINED",
  • "recheckInProgress": "true",
  • "created": "2019-05-16T07:31:07.398Z",
  • "uploaded": "2019-05-16T07:31:07.338Z",
  • "name": "Photo documentation of the object",
  • "note": "Photographed with a mobile phone",
  • "downloadPasswordProtected": "true",
  • "size": "892612",
  • "recipients": [
    ],
  • "flags": [
    ],
  • "accessType": "PUBLIC",
  • "encryptionStatus": "NOT_ENCRYPTED",
  • "encryptionType": "NONE",
  • "dataIntegrity": "UNKNOWN",
  • "approveRequired": "true",
  • "approved": "2019-05-16T07:31:07.398Z",
  • "disapproved": "2019-05-16T07:31:07.398Z",
  • "limitAccessCount": "0",
  • "accessCount": "0",
  • "rootFolderId": "0b17c541-206d-4bbc-b6e9-dc3d312ff54d",
  • "passwordToken": {
    }
}

Updates package attributes

Updates the attributes of package packageId. Only the data sent in the request are updated, the rest remain unchanged.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
name
string <= 100 characters

Package name

note
string <= 10000 characters

Note

accessType
string
Enum: "PUBLIC" "PRIVATE" "INTERNAL"

Accessibility of the package.

Possible values:

  • PUBLIC - public
  • PRIVATE - private
  • INTERNAL - internal

This attribute is available only to the administrator.

downloadPassword
string <= 30 characters

Password for downloading the package. The password cannot be changed if data encryption by the package password is active.

downloadExpiration
string <date-time>

End time of package validity (date and time)

persistent
boolean
Default: false

Persistent package (with unlimited validity).

This attribute is available only to the user with the appropriate permission or to the administrator.

Responses

Request samples

Content type
application/json
{
  • "name": "Photo documentation of the object",
  • "note": "Photographed with a mobile phone",
  • "accessType": "PUBLIC",
  • "downloadPassword": "password123",
  • "downloadExpiration": "2023-06-01T00:00:00+02:00",
  • "persistent": "true"
}

Deleting the package

Deletes the package packageId including all folders and files.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Returns a list of package tags

Returns the list of package tags.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Response samples

Content type
application/json
[
  • "task:completed"
]

Adding tags to the package

Adds tags to the package (if they do not already exist for the package).

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "task:completed"
]

Sets tags on the package

Sets tags on the package (overwrites the current state).

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "task:completed"
]

Removes tags from the package

Removes the specified tags from the package (if they are on the package).

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
Array
string <= 100 characters

Responses

Request samples

Content type
application/json
[
  • "task:completed"
]

Creates a new token for access to the package with a limited number of accesses

Creates a new time-limited limitAccessToken for access to the package with a limited number of accesses.

Creating a new token will use up one allowed access.

The token must be present in the HTTP header X-Sofie-Limit-Access-Token in subsequent requests.

The operation can only be called by a regular user.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password

Responses

Response samples

Content type
application/json
{
  • "limitAccessToken": "eyJ...w5c",
  • "expiresAt": "2025-03-15T12:34:56Z"
}

Shreds (permanently deletes) the package

Shreds (permanently deletes) the package packageId and all its contents.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

Responses

Adds new recipients

Adds new recipients to the package packageId. New recipients can only be obtained for an active package that is not in quarantine.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
Array
type
required
string
Enum: "REGULAR" "BLIND" "CONTRIBUTOR"

Recipient type

email
required
string <email> <= 100 characters

Recipient's email

Responses

Request samples

Content type
application/json
[]

Creates a new token for access to a password-protected package

Creates a new time-limited passwordToken for access to a password-protected package.

The token must be present in subsequent requests in the HTTP header X-Sofie-Password-Token.

The operation can be called by a regular user and an administrator.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

Request Body schema: application/json
required
password
required
string <= 100 characters

Package password

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "passwordToken": "eyJ...w5c",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Unsubscribe recipient

Removes recipient recipientId from package packageId. Only internal recipients can be removed.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

recipientId
required
string <uuid>
Example: c1252659-01b2-4b71-8ef1-e65c86aba002

Recipient ID

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Folder management

Operations for managing folders in packages.

Creates a new folder

Creates a new folder in the package packageId.

The operation can only be called by a regular user.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
parentId
required
string <uuid>

The ID of the parent folder in which the new folder is to be created.

name
required
string <= 255 characters

Folder name

conflictResolution
string (ConflictResolutionFolderName)
Enum: "REPLACE" "RENAME_NEW" "RENAME_EXISTING" "DENY"

Requested behavior when there is a folder name conflict.

Possible values:

  • REPLACE - replacement (deletion) of the existing item
  • RENAME_NEW - automatic renaming of the new item (a suffix with a counter is placed at the end of the folder name)
  • RENAME_EXISTING - automatic renaming of the existing item (a suffix with a counter is placed at the end of the item name)
  • DENY - in case of a name conflict, the action is denied

The default value is RENAME.

Responses

Request samples

Content type
application/json
{
  • "parentId": "0584e5fb-9545-4538-a1fe-57b14194d11b",
  • "name": "New folder",
  • "conflictResolution": "RENAME"
}

Response samples

Content type
application/json
{
  • "id": "f7dfcb3b-a9cf-414a-9253-02489c21aa3f",
  • "renamedFolders": [
    ],
  • "renamedFiles": [
    ],
  • "replacedFolders": [
    ],
  • "replacedFiles": [
    ],
  • "name": "string"
}

Deletes the folder

Deletes the folder folderId of package packageId and all its contents.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

folderId
required
string <uuid>
Example: ccdd4a54-df58-4bf9-ae6a-cd8173de8732

ID of the folder returned by the server upon its creation

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Shreds (permanently deletes) the folder

Shreds (permanently deletes) the folder folderId of package packageId and all its contents.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

folderId
required
string <uuid>
Example: ccdd4a54-df58-4bf9-ae6a-cd8173de8732

ID of the folder returned by the server upon its creation

Responses

Changing folder name

Changes the folder name folderId of the package packageId.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

folderId
required
string <uuid>
Example: ccdd4a54-df58-4bf9-ae6a-cd8173de8732

ID of the folder returned by the server upon its creation

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Modified folder"
}

Returns the contents of the folder

Returns the content of the folderId folder of the packageId package.

The operation can be called by a regular user and an administrator. Only the administrator can see shredded items.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

folderId
required
string <uuid>
Example: ccdd4a54-df58-4bf9-ae6a-cd8173de8732

ID of the folder returned by the server upon its creation

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Response samples

Content type
application/json
{
  • "folders": [
    ],
  • "files": [
    ]
}

File management

Operations for managing files in package folders.

Creates a new file

Creates metadata for a new file in the folderId folder of the packageId package for subsequent content upload. The file is in the UPLOADING state after creation.

The operation can only be called by a regular user.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

folderId
required
string <uuid>
Example: ccdd4a54-df58-4bf9-ae6a-cd8173de8732

ID of the folder returned by the server upon its creation

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
name
required
string <= 255 characters

Filename

conflictResolution
string (ConflictResolutionFileName)
Enum: "REPLACE" "RENAME_NEW" "RENAME_EXISTING" "DENY"

Required behavior in case of a file name conflict.

Possible values:

  • REPLACE - replacement (deletion) of the existing item
  • RENAME_NEW - automatic renaming of the new item (a suffix with a counter is added to the end of the file name)
  • RENAME_EXISTING - automatic renaming of the existing item (a suffix with a counter is added to the end of the item's name)
  • DENY - in case of a name conflict, the action is denied

The default value is RENAME.

size
required
number

File size in bytes

mimeType
string <= 100 characters
Default: "application/octet-stream"

MIME type of the file

hash
string

SHA-256 hash of the file content. If this optional attribute is present in the request, the server searches for existing files with the same name and hash. If an existing file is found, a list of existing files with the same name and hash is returned instead of creating a new file.

Responses

Request samples

Content type
application/json
{
  • "name": "WP_20151010_001.jpg",
  • "conflictResolution": "RENAME",
  • "size": "1605184",
  • "mimeType": "image/jpeg",
  • "hash": "06326674220464174b719f7ecc3a465ad4d3a52a765bb866ddd451a1a51d0b88"
}

Response samples

Content type
application/json
{
  • "id": "0e665ed0-3914-4744-ba54-4f3eb110ffeb",
  • "renamedFolders": [
    ],
  • "renamedFiles": [
    ],
  • "replacedFolders": [
    ],
  • "replacedFiles": [
    ],
  • "name": "string"
}

Returns information about the file

Returns detailed information about the file fileId of the package packageId.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Response samples

Content type
application/json
{
  • "id": "0f6a621a-e59f-4f52-ac17-68b38e17c2f6",
  • "name": "WP_20151010_001.jpg",
  • "path": "/Folder/Nested folder/WP_20151010_001.jpg",
  • "size": "1605184",
  • "hash": "06326674220464174b719f7ecc3a465ad4d3a52a765bb866ddd451a1a51d0b88",
  • "mimeType": "image/jpeg",
  • "state": "CLEAN",
  • "recheckInProgress": "true",
  • "created": "2019-05-16T07:31:07.338Z",
  • "uploaded": "2019-05-16T07:31:07.338Z",
  • "deleted": "2019-05-16T07:31:07.338Z",
  • "contentDeleted": "2019-05-16T07:31:07.338Z",
  • "checks": [],
  • "flags": [
    ]
}

Deleting file

Deletes the file fileId of the package packageId. The operation can only be called on files in the CLEAN and UNCLEAN state.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Changes the file name

Changes the file name fileId of the package packageId.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "New file name"
}

Downloading file content

Downloads the content of the file fileId in the folder folderId of the package packageId. The operation can only be called for files in the CLEAN state.

The operation can be called by a regular user and an administrator.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Saves the content of the file

Stores the content of the file fileId of the package packageId.
The request body is in binary form.
The operation can only be called for files in the UPLOADING state.

The operation can only be called by a regular user.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/octet-stream
required
string <binary>

Responses

Shreds (permanently deletes) the file

Shreds (permanently deletes) the file fileId of the package packageId.

Only an administrator can call the operation.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Responses

Confirms or cancels file content upload

Confirms or cancels the upload of the content of the file fileId in the package packageId. The type of operation is determined by the value of the attribute state in the request body. The operation can only be called for files in the UPLOADING state.

Only a regular user can call the operation.

Authorizations:
bearerAuth
path Parameters
packageId
required
string <uuid>
Example: 28ec36f3-9c1f-4e3a-b907-f42e85ffcdd4

ID of the package returned by the server when it is created

fileId
required
string <uuid>
Example: 0e665ed0-3914-4744-ba54-4f3eb110ffeb

File ID returned by the server when initiating a package

header Parameters
X-Sofie-Password-Token
string <= 1000 characters

Token for access to a password-protected package.

You can obtain the token either:

  • by calling POST /packages/{packageId}/password-token with the package password, or
  • as part of the response of GET /packages/{packageId} when the request includes header X-Sofie-Download-Password with a valid password
X-Sofie-Limit-Access-Token
string <= 1000 characters
Example: eyJ...w5c

Token for access to the package with a limited number of accesses.

Request Body schema: application/json
required
state
required
string
Enum: "UPLOADED" "CANCELED"

Requested file status.

Possible values:

  • UPLOADED - file content upload has been completed
  • CANCELED - file content upload has been canceled (file status changes to UPLOAD_CANCELED)
hash
string

SHA-256 hash of the file.

If this hash does not match the hash of the file on the server, HTTP code 412 is returned and the status of the file on the server remains unchanged.

Responses

Request samples

Content type
application/json
{
  • "state": "UPLOADED",
  • "hash": "06326674220464174b719f7ecc3a465ad4d3a52a765bb866ddd451a1a51d0b88"
}

User management

Operations for user management. All operations can only be performed by the administrator.

Returns a list of users

Returns a list of users.

The operation can only be called by an administrator.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Creating a new user

Creates a new local user.

The operation can be called only by an administrator.

Authorizations:
bearerAuth
Request Body schema: application/json
username
required
string

Username

firstName
string

Name

lastName
string

Surname

email
required
string

E-mail

company
string

Company

phoneNumber
string

Phone number

ipRanges
string

List of allowed IP ranges in CIDR format separated by a comma

language
string
Enum: "EN" "CS" "SK" "HU"

Preferred language

expireAt
string <date-time>

Date of automatic user deletion

sshPublicKeys
string

List of public SSH keys in the OpenSSH authorized_keys file format (e.g. "ssh-rsa AAAAB3NzaC1y..."). Only one key per line is allowed.

defaultSftpPackage
string <uuid>

Package that will be accessed via SFTP in case the package ID is not present in the username (e.g., "document-exchange@sofie.cloud#4f23f924-e08b-404e-b7b1-806364763126").

enabled
boolean

If true, the user is active and can log in.

password
string

Password.

sendResetPasswordToken
boolean

Send a link to set a password. Required if the password attribute is not set.

Responses

Request samples

Content type
application/json
{
  • "username": "document-exchange",
  • "firstName": "Document",
  • "lastName": "Exchange",
  • "email": "[email protected]",
  • "company": "SOFiE",
  • "phoneNumber": "123 456 798",
  • "ipRanges": "10.0.0.0/24, 192.168.0.0/16",
  • "language": "EN",
  • "expireAt": "Thu Jun 01 02:00:00 CEST 2023",
  • "sshPublicKeys": "ssh-rsa AAA...knQ== [email protected] \nssh-ed25519 AAA...Py5 [email protected]\n",
  • "defaultSftpPackage": "4f23f924-e08b-404e-b7b1-806364763126",
  • "enabled": "true",
  • "password": "password123",
  • "sendResetPasswordToken": "false"
}

Response samples

Content type
application/json
{
  • "id": "6cfb02e8-fa59-4ed6-ae14-547100ed9413"
}

Returns information about the user

Returns information about the user userId.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>
Example: 9af903c5-8f4a-4024-84d2-7907ce9a0fd1

User ID

Responses

Response samples

Content type
application/json
{
  • "id": "079f1218-8b65-447d-9371-9f753fd1d841",
  • "username": "document-exchange",
  • "firstName": "Document",
  • "lastName": "Exchange",
  • "email": "[email protected]",
  • "company": "SOFiE",
  • "phoneNumber": "123 456 798",
  • "ipRanges": "10.0.0.0/24, 192.168.0.0/16",
  • "language": "EN",
  • "expireAt": "Thu Jun 01 02:00:00 CEST 2023",
  • "sshPublicKeys": "ssh-rsa AAA...knQ== [email protected] \nssh-ed25519 AAA...Py5 [email protected]\n",
  • "defaultSftpPackage": "4f23f924-e08b-404e-b7b1-806364763126",
  • "enabled": "true",
  • "userGroups": [
    ]
}

Updates user attributes

Updates the attributes of the user userId. Only the data sent in the request is updated, others remain unchanged.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>
Example: 9af903c5-8f4a-4024-84d2-7907ce9a0fd1

User ID

Request Body schema: application/json
username
string

Username

firstName
string

Name

lastName
string

Surname

email
string

E-mail

company
string

Company

phoneNumber
string

Phone number

ipRanges
string

List of allowed IP ranges in CIDR format separated by a comma

language
string
Enum: "EN" "CS" "SK" "HU"

Preferred language

expireAt
string <date-time>

Date of automatic user deletion

sshPublicKeys
string

List of public SSH keys in the OpenSSH authorized_keys file format (e.g. "ssh-rsa AAAAB3NzaC1y..."). Only one key per line is allowed.

defaultSftpPackage
string <uuid>

Package that will be accessed via SFTP in case the package ID is not present in the username (e.g., "document-exchange@sofie.cloud#4f23f924-e08b-404e-b7b1-806364763126").

enabled
boolean

If true, the user is active and can log in.

password
string

Password

clearExpireAt
boolean

If true, cancels the automatic deletion date of the user

Responses

Request samples

Content type
application/json
{
  • "username": "document-exchange",
  • "firstName": "Document",
  • "lastName": "Exchange",
  • "email": "[email protected]",
  • "company": "SOFiE",
  • "phoneNumber": "123 456 798",
  • "ipRanges": "10.0.0.0/24, 192.168.0.0/16",
  • "language": "EN",
  • "expireAt": "Thu Jun 01 02:00:00 CEST 2023",
  • "sshPublicKeys": "ssh-rsa AAA...knQ== [email protected] \nssh-ed25519 AAA...Py5 [email protected]\n",
  • "defaultSftpPackage": "4f23f924-e08b-404e-b7b1-806364763126",
  • "enabled": "true",
  • "password": "password123",
  • "clearExpireAt": "true"
}

Deletes user

Deletes the user userId.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>
Example: 9af903c5-8f4a-4024-84d2-7907ce9a0fd1

User ID

Responses

User group management

Operations for managing user groups. Only the administrator can perform all operations.

The application supports these permissions for user groups:

  • LOGIN — Login
  • RECEIVE_PACKAGE — Receive packages
  • SEND_PACKAGE__PUBLIC — Send packages — public
  • SEND_PACKAGE__INTERNAL — Send packages — internal
  • SEND_PACKAGE__PRIVATE — Send packages — private
  • SEND_PACKAGE__BRIEFCASE — Use briefcase
  • CREATE_ACCESS_LINK__PUBLIC — Share packages — public
  • CREATE_ACCESS_LINK__INTERNAL — Share packages — internal
  • CREATE_ACCESS_LINK__PRIVATE — Share packages — private
  • ALLOW_DOWNLOAD_WITHOUT_LOGIN — Download files without login password
  • PASSWORD_ENCRYPTION — Encrypt sent packages with a password
  • MFA_NOT_REQUIRED — Do not enforce multi‑factor authentication
  • SEND_PACKAGE_WITHOUT_APPROVAL — Send packages without additional approval
  • APPROVE_SEND_PACKAGE — Approve sending packages
  • ACCESS_ALL_PACKAGES_FOR_APPROVE — Access all packages requiring approval (requires permission APPROVE_SEND_PACKAGE)
  • SEND_PACKAGE_TO_YOURSELF — Send packages to yourself
  • ALLOW_DOWNLOAD_SENT_FILES — Download files from your sent packages
  • FILE_CHECK_RESULT_DETAILS — Access detailed check results
  • SET_APPROVER — Choose approver of sent packages
  • COOPERATIVE_PACKAGES — Create cooperative packages
  • SET_PACKAGE_PERSISTENT — Set package as persistent
  • PERSISTENT_ACCOUNT — Persistent account
  • SFTP_ACCESS_ALLOWED — Access packages via SFTP
  • ALLOW_ADD_AND_MANAGE_FILES_IN_QUARANTINE — Add and manage package files in quarantine
  • ALLOW_DELETE_FILES_IN_QUARANTINE — Delete files in packages in quarantine
  • LOG_ACCESS — Access to audit log
  • LOG_ACCESS_EXTENDED — Access to extended audit log (requires permission LOG_ACCESS)
  • PASSWORD_RECOVERY — Recover password

Returns a list of user groups

Returns a list of user groups.

Without specifying the parameter $top, 100 records are returned; the maximum value of the parameter $top and thus the number of returned records is 5000.

The following operators and attributes are supported for the URL parameter $filter (see the Data filtering section):

  • ==: name
  • contains: name
  • icontains: name
  • in: permissions

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
query Parameters
$top
integer
Example: $top=100

The maximum number of records to be returned (usable for pagination).

$skip
integer
Example: $skip=100

Number of records to be skipped (applicable for pagination).

$filter
string
Example: $filter={"and":[{"==":[{"var":"name"},"Project summary"]},{"in":["done",{"var":"tags"}]}]}

JSON filter expression in JsonLogic format (sent as a URL‑encoded string). Supported operators and attributes are listed for each operation.

Responses

Response samples

Content type
application/json
{
  • "total": 5660,
  • "count": 100,
  • "data": [
    ]
}

Creates a new user group

Creates a new user group.

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string <= 100 characters

Group name

email
string <email> <= 100 characters

E-mail

distribution
boolean

True if it is a distribution group

permissions
Array of strings (UserPermission)
Items Enum: "LOGIN" "RECEIVE_PACKAGE" "SEND_PACKAGE__PUBLIC" "SEND_PACKAGE__INTERNAL" "SEND_PACKAGE__PRIVATE" "SEND_PACKAGE__BRIEFCASE" "CREATE_ACCESS_LINK__PUBLIC" "CREATE_ACCESS_LINK__INTERNAL" "CREATE_ACCESS_LINK__PRIVATE" "ALLOW_DOWNLOAD_WITHOUT_LOGIN" "PASSWORD_ENCRYPTION" "MFA_NOT_REQUIRED" "SEND_PACKAGE_WITHOUT_APPROVAL" "APPROVE_SEND_PACKAGE" "ACCESS_ALL_PACKAGES_FOR_APPROVE" "SEND_PACKAGE_TO_YOURSELF" "ALLOW_DOWNLOAD_SENT_FILES" "FILE_CHECK_RESULT_DETAILS" "SET_APPROVER" "COOPERATIVE_PACKAGES" "SET_PACKAGE_PERSISTENT" "PERSISTENT_ACCOUNT" "SFTP_ACCESS_ALLOWED" "ALLOW_ADD_AND_MANAGE_FILES_IN_QUARANTINE" "ALLOW_DELETE_FILES_IN_QUARANTINE" "LOG_ACCESS" "LOG_ACCESS_EXTENDED" "PASSWORD_RECOVERY"

Permissions assigned to the group

accessibility
required
string
Enum: "PUBLIC" "INTERNAL" "PRIVATE"

Accessibility of the group.

Possible values:

  • PUBLIC — public
  • INTERNAL — internal
  • PRIVATE — private

Responses

Request samples

Content type
application/json
{
  • "name": "Users",
  • "email": "[email protected]",
  • "distribution": true,
  • "permissions": [
    ],
  • "accessibility": "PUBLIC"
}

Response samples

Content type
application/json
{
  • "id": "8216edb8-2fca-4391-a41c-64e9acf1c871"
}

Returns information about a user group

Returns information about the user group userGroupId.

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

Responses

Response samples

Content type
application/json
{
  • "id": "c3cddaf7-450a-4da1-bf8e-9d5e31048587",
  • "name": "Users",
  • "email": "[email protected]",
  • "distribution": true,
  • "permissions": [
    ],
  • "accessibility": "PUBLIC",
  • "createdAt": "2023-06-01T00:00:00Z"
}

Updates user group attributes

Updates the attributes of the user group userGroupId. Only the fields sent in the request are updated.

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

Request Body schema: application/json
name
string <= 100 characters

Group name

email
string <email> <= 100 characters

E-mail

distribution
boolean

True if it is a distribution group

permissions
Array of strings (UserPermission)
Items Enum: "LOGIN" "RECEIVE_PACKAGE" "SEND_PACKAGE__PUBLIC" "SEND_PACKAGE__INTERNAL" "SEND_PACKAGE__PRIVATE" "SEND_PACKAGE__BRIEFCASE" "CREATE_ACCESS_LINK__PUBLIC" "CREATE_ACCESS_LINK__INTERNAL" "CREATE_ACCESS_LINK__PRIVATE" "ALLOW_DOWNLOAD_WITHOUT_LOGIN" "PASSWORD_ENCRYPTION" "MFA_NOT_REQUIRED" "SEND_PACKAGE_WITHOUT_APPROVAL" "APPROVE_SEND_PACKAGE" "ACCESS_ALL_PACKAGES_FOR_APPROVE" "SEND_PACKAGE_TO_YOURSELF" "ALLOW_DOWNLOAD_SENT_FILES" "FILE_CHECK_RESULT_DETAILS" "SET_APPROVER" "COOPERATIVE_PACKAGES" "SET_PACKAGE_PERSISTENT" "PERSISTENT_ACCOUNT" "SFTP_ACCESS_ALLOWED" "ALLOW_ADD_AND_MANAGE_FILES_IN_QUARANTINE" "ALLOW_DELETE_FILES_IN_QUARANTINE" "LOG_ACCESS" "LOG_ACCESS_EXTENDED" "PASSWORD_RECOVERY"

Permissions assigned to the group

accessibility
string
Enum: "PUBLIC" "INTERNAL" "PRIVATE"

Accessibility of the group.

Possible values:

  • PUBLIC — public
  • INTERNAL — internal
  • PRIVATE — private

Responses

Request samples

Content type
application/json
{
  • "name": "Users",
  • "email": "[email protected]",
  • "distribution": true,
  • "permissions": [
    ],
  • "accessibility": "PUBLIC"
}

Deletes a user group

Deletes the user group userGroupId.

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

Responses

Returns the list of group members

Returns the list of members of the group userGroupId.

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

query Parameters
$top
integer
Example: $top=100

The maximum number of records to be returned (usable for pagination).

$skip
integer
Example: $skip=100

Number of records to be skipped (applicable for pagination).

Responses

Response samples

Content type
application/json
{
  • "total": 5660,
  • "count": 100,
  • "data": [
    ]
}

Adds users to the group

Adds users to the group (if they are not already members).

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

Request Body schema: application/json
required

List of unique user IDs

Array
string

Responses

Request samples

Content type
application/json
[
  • "bfe44611-f0d0-48af-9334-2026d9707ada"
]

Sets the users in the group

Sets the users in the group (overwrites the current state).

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

Request Body schema: application/json
required

List of unique user IDs

Array
string

Responses

Request samples

Content type
application/json
[
  • "bfe44611-f0d0-48af-9334-2026d9707ada"
]

Removes a user from the group

Removes the user userId from the group userGroupId (if they are a member).

Only the administrator can call this operation.

Available since version 2.5.0.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>
Example: 9af903c5-8f4a-4024-84d2-7907ce9a0fd1

User ID

userGroupId
required
string <uuid>
Example: a4d00b03-7de3-4e23-9779-20704ecc5ee0

User group ID

Responses

API token management

Operations for managing API tokens. All operations can be performed only by the administrator.

Returns a list of API tokens

Returns a list of all API tokens. The JWT token itself usable for authentication is not part of the response (it is only available immediately after creating a new token).

The operation can only be called by an administrator.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new API token

Creates a new API token for authentication within the HTTP API. The API token must be associated with a specific user or administrator.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "USER"

Type of API token

userId
required
string

User ID

name
required
string

API token name

ipRanges
string

List of allowed IP ranges in CIDR format separated by commas

Responses

Request samples

Content type
application/json
{
  • "type": "ADMIN",
  • "adminId": "0a740457-2718-4f97-b12b-a52d69c2fae7",
  • "name": "API token",
  • "ipRanges": "10.0.0.0/24, 192.168.0.0/16"
}

Response samples

Content type
application/json
{
  • "id": "d6bd3332-dfa4-4670-a93d-3fa4b9845154",
  • "token": "eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJzb2ZpZS5jbG91ZCIsInN1YiI6ImRvY3VtZW50LWV4Y2hhbmdlIiwidWlkIjoiY2UwOGU4ZWMtMmVhZC00OGVmLWIxM2ItNmRmY2UwNjM4MDU1IiwiYXBpVG9rZW5JZCI6Ijc1ZDI4NmVmLWExNjgtNGZmMy1iNWM3LWNjZmRhYTdmODJjOSIsInJvbGUiOiJ1c2VyIiwiaXNzIjoic29maWUuY2xvdWQiLCJpYXQiOjE3MTgyODMyMjV9.97goxHPL61riLrvUBhHjltZgoQvPFM7sbaii_C6J7HU"
}

Returns API token details

Returns the details of the API token apiTokenId. The JWT token itself, which can be used for authentication, is not part of the response (it is only available immediately after creating a new token).

The operation can only be called by an administrator.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "adminId": "0a740457-2718-4f97-b12b-a52d69c2fae7",
  • "id": "d6bd3332-dfa4-4670-a93d-3fa4b9845154",
  • "name": "API token",
  • "type": "USER",
  • "ipRanges": "10.0.0.0/24, 192.168.0.0/16",
  • "token": "eyJhbGciOi...1A5rSq2-hk"
}

Deletes API token

Deletes API token apiTokenId.

The operation can only be called by an administrator.

Authorizations:
bearerAuth
path Parameters
apiTokenId
required
string <uuid>
Example: d5b02667-e64e-4d99-bb93-9aff35885348

ID API token

Responses