ONLYOFFICE DocSpace Portal API

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

authenticateMeFromBodyWithCode

AuthenticationTokenWrapper authenticateMeFromBodyWithCode(code, AuthWithCodeRequestsDto)

POST /api/2.0/authentication/{code}

Authenticate a user by code

Finishes a two-factor sign-in: checks the one-time code and, when it matches, issues the authentication token. Call it only after POST api/2.0/authentication answered with sms or tfa set, and repeat the same credentials in the body next to code - the code alone does not identify the user. The code comes from the SMS the portal sent, which POST api/2.0/authentication/sendsms resends, or from the authenticator app; whichever second factor the portal has enabled for this user is the one checked here. Open to unauthenticated callers, mutating and not idempotent: a code is single-use, the sign-in is written to the login history, and the first code accepted from an authenticator app also connects that app to the user. The answer carries token for the Authorization header, expires unless session=true tied the token to the browser session, and either sms with the masked phone number or tfa. A wrong, empty or expired code fails with 401 and counts against the brute-force limit, which then refuses further attempts with 403.

Parameters

Name	In	Type	Description	Notes
code	path	String	The two-factor authentication code. Send the same value as the `code` of the request body, which is the one the handler reads.	[required]
AuthWithCodeRequestsDto	body	AuthWithCodeRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The authentication token to send in the `Authorization` header, together with the second factor that was accepted	AuthenticationTokenWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request body could not be validated, for example `confirmData.email` is not an email address	-	-
401	The credentials were rejected, or the two-factor code is wrong, empty or expired	-	-
403	The user is disabled, or too many failed attempts have blocked further sign-ins for these credentials	-	-
404	No user of this portal matches the credentials in the request body	-	-
429	The portal rate limiter rejected the call - retry after the interval in the `Retry-After` header	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

checkConfirm

ConfirmWrapper checkConfirm(EmailValidationKeyModel)

POST /api/2.0/authentication/confirm

Check a confirmation link

Checks the key of a confirmation link that the portal sent by email and reports whether the action behind that link can still be carried out - an employee invitation, phone activation, a password change, portal removal and so on. Take key and type from the query string of the link; when key is left empty, the key saved in the confirmation cookie of the same type is used instead. Open to unauthenticated callers and read-only: it neither accepts the invitation nor signs anyone in. result is Ok when the link may be used, Invalid when the key does not match the type or the email, Expired when it is too old, and TariffLimit, UserExisted, UserExcluded or QuotaFailed when the key is sound but the invitation behind it cannot be accepted. Only Ok should be followed by the operation that performs the action - POST api/2.0/people with fromInviteLink for an invitation, POST api/2.0/authentication with confirmData for a sign-in link - and for an invitation to a room the answer also carries the identifier and the title of that room.

Parameters

Name	In	Type	Description	Notes
EmailValidationKeyModel	body	EmailValidationKeyModel		[optional]

Responses

Status code	Description	Type	Response headers
200	Whether the confirmation link may be used, with the room and the email it was issued for when it is an invitation	ConfirmWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The portal's IP restrictions do not allow this address to check an invitation link	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ConfirmWrapper

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

getIsAuthentificated

BooleanWrapper getIsAuthentificated()

GET /api/2.0/authentication

Check authentication

Reports whether the credentials that came with this very request identify a signed-in user of the current portal - the authentication cookie, or the token in the Authorization header. Nothing has to be called first: the operation is open to unauthenticated callers, who simply get false, it is read-only and idempotent, and it answers even while the portal's payment has lapsed. The result is a bare boolean that carries no reason, so false covers a missing, malformed, expired and revoked token alike; the way to recover from it is to sign in again with POST api/2.0/authentication. It says nothing about who the caller is or how long the session still lasts - read GET api/2.0/people/@self for the profile behind the token.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	`true` when the request carries a valid token or cookie of an active portal user, `false` in every other case	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

logout

StringWrapper logout()

POST /api/2.0/authentication/logout

Log out

Ends the session the request itself was made with: the login event behind the authentication cookie is closed, the sockets opened for it are disconnected, the portal cookies are cleared and a logout event is written to the login history. Send it with the cookie or token of the session that is to be closed; an anonymous call is accepted and closes nothing. The operation is mutating and idempotent - the same session cannot be closed twice - and it touches only that one session: the other sessions of the same user stay alive and are ended by PUT api/2.0/security/activeconnections/logoutallexceptthis or PUT api/2.0/security/activeconnections/logout/{loginEventId}. The answer is a single logout URL when the user signed in through SSO and the portal has an SLO endpoint configured, and the client has to open that URL to end the session on the identity provider as well; for everyone else it is empty and nothing more is needed.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The single logout URL to open when the user signed in through SSO, or an empty result when no further action is needed	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveMobilePhone

AuthenticationTokenWrapper saveMobilePhone(MobileRequestsDto)

POST /api/2.0/authentication/setphone

Set a mobile phone

Stores the mobile phone number of a user who is going through phone activation and sends the first SMS authentication code to it. It is reachable only with the phone-activation confirmation link that POST api/2.0/authentication returns in confirmUrl when SMS two-factor is required and the user has no activated number yet: that link authorizes the call in place of an authentication token, and no token is issued here. The operation is mutating and not idempotent - it saves the number as not activated, writes an audit event and sends a message - and an already activated number is not replaced this way, the stored number has to be erased first. The answer carries sms, the masked number and expires, the moment the code stops being accepted. Submit that code to POST api/2.0/authentication/{code}, which signs the user in and marks the number activated, or ask for another one with POST api/2.0/authentication/sendsms.

Parameters

Name	In	Type	Description	Notes
MobileRequestsDto	body	MobileRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The masked phone number the code was sent to and the moment that code expires - no authentication token yet	AuthenticationTokenWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

sendSmsCode

AuthenticationTokenWrapper sendSmsCode(AuthRequestsDto)

POST /api/2.0/authentication/sendsms

Send SMS code

Sends a new SMS authentication code to the phone number stored for the user and reports when that code expires. The credentials in the body are checked exactly as by POST api/2.0/authentication, so use this operation to resend the code after that call answered with sms; the user needs SMS two-factor enabled and a phone number already stored, which POST api/2.0/authentication/setphone registers. Open to unauthenticated callers, mutating and not idempotent: every call sends a message, is counted in the portal's SMS usage and spends one of the few codes a number is allowed within the code lifetime (ten minutes by default), after which the call fails until those codes expire. Codes sent earlier stay valid, so a resent code does not invalidate them, and the first one to be accepted invalidates all of them. The answer carries sms, the masked number and expires, and no token - submit the code to POST api/2.0/authentication/{code}.

Parameters

Name	In	Type	Description	Notes
AuthRequestsDto	body	AuthRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The masked phone number the code was sent to and the moment that code expires - no authentication token yet	AuthenticationTokenWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request body could not be validated, for example `confirmData.email` is not an email address	-	-
401	The password, the confirmation key or the third-party profile was rejected	-	-
403	The user is disabled, or too many failed attempts have blocked further sign-ins for these credentials	-	-
404	No user of this portal matches the credentials in the request body	-	-
429	The portal rate limiter rejected the call - retry after the interval in the `Retry-After` header	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

CapabilitiesApi

getPortalCapabilities

CapabilitiesWrapper getPortalCapabilities()

GET /api/2.0/capabilities

Get portal capabilities

Returns the sign-in methods this portal offers, which a login client needs before anyone has signed in: LDAP authentication and its domain, the external identity providers to show, the SAML single sign-on URL and its label, and whether the built-in identity server is available. No token is needed and nothing has to be called first - the operation is open to unauthenticated callers, answers even while the portal's payment has lapsed, and is read-only and idempotent. providers holds provider keys such as google or facebook, ordered for the country detected from the caller's IP address and reduced to the ones this installation has configured; pass one of them as provider to POST api/2.0/authentication. An empty providers means external sign-in is off and an empty ssoUrl means single sign-on is off; a capability whose settings cannot be read is reported as disabled rather than failing the call, so a false flag means the method is not offered, not that it is unknown. The answer describes the portal and never a user, and carries none of the configuration behind these methods: an administrator reads that from GET api/2.0/settings/ssov2 and GET api/2.0/settings/authservice.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The sign-in methods the portal offers: LDAP, the external identity providers, single sign-on and the identity server, each with the state it has for this portal	CapabilitiesWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CapabilitiesWrapper

Authorization

MigrationStatusWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

MigrationApi

cancelMigration

cancelMigration()

POST /api/2.0/migration/cancel

Cancel migration

Stops the parse pass queued for this portal and deletes the backup uploaded for it - the way back from a wrong archive or a wrong migrator name. Nothing has to be called first and a DocSpace administrator is required; the request is only queued, so the parse ends shortly after the call returns and GET api/2.0/migration/status stops reporting it. The call is destructive for the uploaded data: the whole upload folder is removed and the backup has to be sent to migrationFileUpload.ashx again before a new parse. It is idempotent - cancelling when nothing is running still answers 200 - and it undoes nothing that was already written to the portal. Only the parse stage is stopped, the job whose parseResult.operation is parse: an import started by POST api/2.0/migration/migrate keeps running, and a finished import is discarded with POST api/2.0/migration/clear instead.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The cancellation has been queued; the parse stops and the uploaded backup is deleted. The response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

clearMigration

clearMigration()

POST /api/2.0/migration/clear

Clear migration

Discards a finished import and deletes the data uploaded for it, freeing the portal for the next one. Call it once GET api/2.0/migration/status reports isCompleted for a job whose parseResult.operation is migration; a DocSpace administrator is required. Only the queued job and the temporary upload folder go - the users, groups and files already imported stay in the portal - so the call destroys migration data alone, and it is idempotent: clearing twice, or with nothing to clear, still answers 200. Like the other write operations here it is only queued, and once it has run GET api/2.0/migration/status returns an empty result and GET api/2.0/migration/logs answers 404, so download the log before calling it. A parse that is still running is not affected - stop that with POST api/2.0/migration/cancel - and POST api/2.0/migration/finish performs the same clean-up itself, which makes this call unnecessary after it.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The clean-up has been queued; the finished import is dropped and the uploaded data deleted. The response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

finishMigration

finishMigration(FinishDto)

POST /api/2.0/migration/finish

Finish migration

Closes a completed import: it can send every user the import created the activation email they need before they can sign in, and it then discards the job and the data uploaded for it. Call it once GET api/2.0/migration/status reports isCompleted for the import; a DocSpace administrator is required, and with isSendWelcomeEmail set to true the job must still be in the queue, so do not clear it first. That flag decides what happens to the imported people: true mails the activation link to each of them who has not activated their account yet and skips the ones that are already active, false ends the import quietly and leaves inviting them for later. The call writes to the portal and is not idempotent - the emails go out again on every call - while its second half repeats what POST api/2.0/migration/clear does, removing the finished job and the uploaded backup and leaving everything already imported in place. It answers with an empty body, after which GET api/2.0/migration/status returns an empty result and GET api/2.0/migration/logs answers 404, so download the log first.

Parameters

Name	In	Type	Description	Notes
FinishDto	body	FinishDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The activation emails have been sent if they were asked for and the clean-up has been queued. The response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getMigrationLogs

getMigrationLogs()

GET /api/2.0/migration/logs

Get migration logs

Downloads the log of the parse or import the portal currently holds - the step-by-step record behind the numbers and the single error message of GET api/2.0/migration/status, and the place where the reason for a skipped user or file is written. The portal has to hold such a job, started by POST api/2.0/migration/init/{migratorName} or POST api/2.0/migration/migrate and not yet removed by POST api/2.0/migration/clear or POST api/2.0/migration/finish, otherwise the call answers 404; a DocSpace administrator is required and the call is read-only and idempotent. The body is not JSON: it is text/plain; charset=UTF-8 sent as an attachment named migration.log, one line per step with the progress it reported. Each job writes its own log, so this always returns the log of the job that GET api/2.0/migration/status describes, and while that job runs the file keeps growing - a call made early returns only the part written so far and may be repeated later for the rest.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The log of the current job as a `text/plain` attachment named `migration.log`	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
404	The portal holds no parse or import whose log could be returned	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getMigrationStatus

MigrationStatusWrapper getMigrationStatus()

GET /api/2.0/migration/status

Get migration status

Returns how far the parse or the import queued for this portal has got and, once it stopped, what it produced - the one place where every other operation in this group reports what it did. Any of them may be polled from here as soon as it returns; a DocSpace administrator is required and the call is read-only and idempotent. progress is the share of the job that is done, from 0 to 100, and isCompleted turns true when the job stopped whether it succeeded or not, so read error as well: it stays empty while nothing went wrong and otherwise holds the message that ended the job. parseResult carries what the migrator has read so far - after a parse pass the users, groups and unreadable archives to edit and post to POST api/2.0/migration/migrate, and during an import also successedUsers and failedUsers - and its operation field, parse or migration, tells the two stages apart. The result is empty with status 200 when the portal has no job at all, because none was ever started or because POST api/2.0/migration/clear or POST api/2.0/migration/finish has removed the last one; an empty answer is therefore not an error. Line-by-line detail behind the numbers is in GET api/2.0/migration/logs.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the parse or import queued for the portal, or an empty result when the portal has no job	MigrationStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

listMigrations

STRINGArrayWrapper listMigrations()

GET /api/2.0/migration/list

Get available migrators

Lists the source products this installation can import a portal from, as the migrator names every other operation in this group expects. Nothing has to be called first, a DocSpace administrator is required as everywhere here, and the call is read-only and idempotent. The answer is a plain list of names such as GoogleWorkspace, Nextcloud or Workspace, never localized and ordered as the migrators are registered; pass one of them as migratorName to POST api/2.0/migration/init/{migratorName}, where the match ignores case. The list depends on the installation rather than on the portal, so it does not change while the portal runs, and a name that is not in it is not rejected by the operation that takes it - the queued job ends with the failure reported in error of GET api/2.0/migration/status.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The names of the migrators this installation can import from, in registration order	STRINGArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

STRINGArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

startMigration

startMigration(MigrationApiInfo)

POST /api/2.0/migration/migrate

Start migration

Starts the import itself: the users, the groups and the files selected in the request body are created on this portal from the backup that the parse pass has read. Run POST api/2.0/migration/init/{migratorName} first and wait for isCompleted in GET api/2.0/migration/status, then send parseResult from that answer back here with shouldImport set on the users and groups to take and the import...Files flags set for the content to copy. A DocSpace administrator is required, and importing a user as DocSpaceAdmin additionally requires the caller to be the portal owner unless a user with that email is an administrator of this portal already, otherwise the whole call is rejected with 403 before anything is imported. The job is queued and the call answers with an empty body at once: watch progress, successedUsers, failedUsers and error in GET api/2.0/migration/status and read what each step did from GET api/2.0/migration/logs. The import writes to the portal and cannot be undone, and a repeat is no help: a call made while the job runs is ignored, and once the job has ended the uploaded backup is deleted, so a new call has nothing to read until the archive is uploaded and parsed again. When the import is done, close it with POST api/2.0/migration/finish, which can also mail the imported users their activation link.

Parameters

Name	In	Type	Description	Notes
MigrationApiInfo	body	MigrationApiInfo		[optional]

Responses

Status code	Description	Type	Response headers
200	The import has been queued; the response carries no content and the progress is read from `GET api/2.0/migration/status`	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request body is missing or could not be read as a parse result	-	-
403	The caller is not a DocSpace administrator, or is not the portal owner and asked to import a user as `DocSpaceAdmin` who is not an administrator of this portal yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

uploadAndInitializeMigration

uploadAndInitializeMigration(migratorName)

POST /api/2.0/migration/init/{migratorName}

Parse migration archive

Queues a pass that reads the backup already uploaded for this portal with the migrator named in the path and reports what it holds - the users, the users that carry no email address, the users that exist on this portal already, the groups and the archives it could not open - so that the caller can choose what to import. Upload the backup first: migrationFileUpload.ashx?Init=true opens a new upload folder and drops the previous one, then every part of the archive is posted to the same handler with Name set to its file name; take migratorName from GET api/2.0/migration/list. A DocSpace administrator is required. The call only queues the job and answers at once with an empty body: poll GET api/2.0/migration/status until isCompleted is true, then read what was found from parseResult and any failure from error. Nothing is imported here and the portal is not changed - the parse result is the body to edit and send to POST api/2.0/migration/migrate. A portal runs one job at a time, so a call made while another parse or import is still running is ignored instead of reported, and a backup bigger than the portal's total storage quota ends the job with an error rather than failing this call.

Parameters

Name	In	Type	Description	Notes
migratorName	path	String	The migrator that knows the format of the uploaded backup. It has to be one of the names `GET api/2.0/migration/list` reports for this installation, spelled exactly as listed.	[required] [example: `GoogleWorkspace`]

Responses

Status code	Description	Type	Response headers
200	The parse job has been queued; the response carries no content and the result is read from `GET api/2.0/migration/status`	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

PortalPaymentApi

calculateWalletPayment

PaymentCalculationWrapper calculateWalletPayment(WalletQuantityRequestDto)

PUT /api/2.0/portal/payment/calculatewallet

Calculate the wallet payment amount

Prices a wallet-service purchase without making it: it returns what buying the requested number of units would cost right now, so a client can show the amount before asking for a confirmation. Only productQuantityType Add (1) is accepted, the quantity must be greater than zero, and the portal needs a billing customer whose wallet has a sub-account in the accounting currency. The caller has to be a DocSpace administrator. Nothing is bought, charged or written down - the call is read-only and may be repeated - and the purchase itself is PUT api/2.0/portal/payment/updatewallet. The answer carries the amount with its currency, the quantity it was computed for and the identifier of the calculation. It is the price of this moment and is not held: it can differ by the time the purchase is made.

Parameters

Name	In	Type	Description	Notes
WalletQuantityRequestDto	body	WalletQuantityRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The amount the purchase would cost, its currency and the quantity it was calculated for	PaymentCalculationWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The quantity type is not `Add`, the quantity is not greater than zero, or the product is not a wallet service	-	-
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer, or its wallet has no sub-account in the accounting currency	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

PaymentCalculationWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeTenantWalletServiceState

TenantWalletServiceSettingsWrapper changeTenantWalletServiceState(ChangeWalletServiceStateRequestDto)

POST /api/2.0/portal/payment/servicestate

Switch a wallet service

Switches one wallet service on or off for the portal: service names it and enabled says which way. The portal needs a billing customer, and the caller needs both the permission to edit the portal settings and DocSpace administrator rights. Order matters between the two AI services - AI tools has to be on before AI search may be switched on, and switching AI tools off switches AI search off with it - so a request that breaks that order is refused with 403. The call is mutating and idempotent: switching on a service that is already on changes nothing. It is written to the portal audit trail, and switching AI tools notifies the portal clients so the AI features appear or disappear for them without a reload. The whole updated set of switched-on services comes back. Switching a service on does not buy it - its units are still bought with PUT api/2.0/portal/payment/updatewallet.

Parameters

Name	In	Type	Description	Notes
ChangeWalletServiceStateRequestDto	body	ChangeWalletServiceStateRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The whole set of wallet services switched on for the portal after the change	TenantWalletServiceSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings or is not a DocSpace administrator, the portal has no billing service configured, or AI search was switched on while AI tools is off	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantWalletServiceSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createCustomerMonthlyUsageReport

DocumentBuilderTaskWrapper createCustomerMonthlyUsageReport(CustomerMonthlyUsageReportRequestDto)

POST /api/2.0/portal/payment/customer/usage/monthly/report

Start the monthly usage report

Queues the wallet spending added up per calendar month as an xlsx file and returns the task that will build it; the file is not ready when the response arrives. The portal needs a billing customer and the caller has to be a DocSpace administrator. The body takes only the period - startDate and endDate, both inclusive - and an empty body covers everything from the portal creation date to now; the months are cut in the portal time zone, exactly as in GET api/2.0/portal/payment/customer/usage/monthly. Poll GET api/2.0/portal/payment/customer/usage/monthly/report until isCompleted is true, then take the file from resultFileUrl or open resultFileId: the finished file is saved into the caller's own My documents section, where it counts against the portal storage like any other file. One monthly usage report per user is tracked at a time - a call made while the previous one is still running answers with that task - and DELETE api/2.0/portal/payment/customer/usage/monthly/report stops it. There is no service filter here: for a report per service use POST api/2.0/portal/payment/customer/usage/report.

Parameters

Name	In	Type	Description	Notes
CustomerMonthlyUsageReportRequestDto	body	CustomerMonthlyUsageReportRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The queued task, to be polled until `isCompleted` is true	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createCustomerOperationsReport

DocumentBuilderTaskWrapper createCustomerOperationsReport(CustomerOperationsReportRequestDto)

POST /api/2.0/portal/payment/customer/operationsreport

Start the operations report

Queues the history of the wallet movements as an xlsx file and returns the task that will build it; the file is not ready when the response arrives. The portal needs a billing customer and the caller has to be a DocSpace administrator. The body takes the same filters as GET api/2.0/portal/payment/customer/operations - the service names, the date range, the participant, the operation type and status, the credit and debit directions and the ordering - and an empty body reports everything from the portal creation date to now; a service name this installation does not sell fails with 404. Poll GET api/2.0/portal/payment/customer/operationsreport until isCompleted is true, then take the file from resultFileUrl or open resultFileId: the finished file is saved into the caller's own My documents section, where it counts against the portal storage like any other file. One operations report per user is tracked at a time - a call made while the previous one is still running answers with that task - and DELETE api/2.0/portal/payment/customer/operationsreport stops it. A build that fails ends the task with error filled in rather than failing this call.

Parameters

Name	In	Type	Description	Notes
CustomerOperationsReportRequestDto	body	CustomerOperationsReportRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The queued task, to be polled until `isCompleted` is true	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer, or one of the names in `serviceName` is not a wallet service of this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createCustomerServiceUsageReport

DocumentBuilderTaskWrapper createCustomerServiceUsageReport(CustomerServiceUsageReportRequestDto)

POST /api/2.0/portal/payment/customer/usage/report

Start the service usage report

Queues the usage of the wallet services as an xlsx file and returns the task that will build it; the file is not ready when the response arrives. The portal needs a billing customer and the caller has to be a DocSpace administrator. The body takes the same filters as GET api/2.0/portal/payment/customer/usage - the service names, the date range, the participant, the operation status, the usage metadata and the ordering - and an empty body reports every service from the portal creation date to now; a service name this installation does not sell fails with 404. Poll GET api/2.0/portal/payment/customer/usage/report until isCompleted is true, then take the file from resultFileUrl or open resultFileId: the finished file is saved into the caller's own My documents section, where it counts against the portal storage like any other file. One service usage report per user is tracked at a time - a call made while the previous one is still running answers with that task - and DELETE api/2.0/portal/payment/customer/usage/report stops it. It is a different report from the operations one and does not interfere with it: per-movement history is POST api/2.0/portal/payment/customer/operationsreport.

Parameters

Name	In	Type	Description	Notes
CustomerServiceUsageReportRequestDto	body	CustomerServiceUsageReportRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The queued task, to be polled until `isCompleted` is true	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer, or one of the names in `serviceName` is not a wallet service of this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ServicePriceInfoArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getAccountingServicePrices

ServicePriceInfoArrayWrapper getAccountingServicePrices(serviceName, active)

GET /api/2.0/portal/payment/accounting/prices/{serviceName}

Get the service prices from the accounting service

Returns the portal's automatic wallet top-up settings: whether it is switched on, the balance that triggers it, the balance it tops the wallet up to and the currency it charges in. Only a DocSpace administrator may read it, no billing customer is needed, and the call is read-only. A portal that has never configured it gets the defaults rather than an empty result, so enabled is the field that says whether anything happens at all. Two of the values are kept by the portal itself and cannot be set through this API: lowBalanceThreshold is the balance below which the portal warns its administrators by mail, and lowBalanceNotified says whether that warning has already gone out for the current dip. Change the rest with POST api/2.0/portal/payment/topupsettings.

Parameters

Name	In	Type	Description	Notes
serviceName	path	String	The service whose price list is read, named the way the billing catalogue names it, such as `ai-tools` or `backup`. Take the value from the `serviceName` field of `GET api/2.0/portal/payment/walletservices`; a name the accounting service does not price yields an empty list rather than an error.	[required] [example: `ai-tools`] [minLength: 0] [maxLength: 255]
active	query	Boolean	Whether the answer is narrowed to the prices in force at the moment of the call. Leaving it false also returns the retired and the not yet started ones, which is what pricing a movement recorded in the past needs.	[optional] [example: `false`]

Responses

Status code	Description	Type	Response headers
200	The list of the service prices	ServicePriceInfoArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	No permissions to perform this action	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getActiveServices

ActiveServiceArrayWrapper getActiveServices()

GET /api/2.0/portal/payment/activeservices

Get the active wallet services

Lists the wallet services the portal is running right now: the add-ons its plan pays for that are in the active state, plus the ones an administrator switched on by hand in the wallet service settings; the Docs Connect trial is listed as well, although it is not paid from the wallet. Only a DocSpace administrator may call it, no billing customer is needed for it, and the call is read-only. Every item names the service, its title and the unit it is measured in, and says whether it is a subscription; a subscribed service also carries the limit it grants and how much of it is used where that number is known - the editor seats and the editors currently active for Docs Connect, the purchased units and the units already consumed for disk storage. A service listed with no limit is one whose usage is not counted this way, not one without a limit. The catalogue of what could be switched on is GET api/2.0/portal/payment/walletservices, and switching one is POST api/2.0/portal/payment/servicestate.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The wallet services active on the portal, with their limits and usage where those are known	ActiveServiceArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ActiveServiceArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAiPrices

AiPricesWrapper getAiPrices()

GET /api/2.0/portal/payment/ai-prices

Get AI model prices

Returns the price list of the AI features the portal pays for out of its wallet: the chat models with the price of their prompt and completion tokens, the embedding models, the image models with their per-image price, and the web search providers with the price of one search. The installation needs both a billing service and the AI gateway configured, otherwise the answer is 403, and only a DocSpace administrator may read it; the call is read-only. Token prices are normalised per million tokens, and every price is in the single currency the answer names. Each entry carries the model identifier to use when talking to the AI operations, its display alias, its provider with the provider icon, and a link to the model's own page. It is a list of what the models cost and not of what the portal spent - that is GET api/2.0/portal/payment/customer/usage - and it says nothing about which of them are allowed here, which is GET api/2.0/portal/payment/ai-model/restrictions.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The prices of the chat, embedding and image models and of the web search providers, with the currency they are in	AiPricesWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation has no billing service or no AI gateway configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AiPricesWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCheckoutSetupUrl

StringWrapper getCheckoutSetupUrl(BackUrl, SuccessUrl)

GET /api/2.0/portal/payment/checkoutsetupurl

Get the checkout setup page URL

Hands back the hosted page on which a payment method is attached to the portal's billing account, for the case where money has to be taken later - a wallet top-up or an automatic one - rather than a plan bought now. A portal that already has a payment method on file answers with an empty result; a DocSpace administrator may ask for the page, but once the portal has a billing customer with an e-mail, only its payer may. The call itself changes nothing and may be repeated: the payment method is stored by the payment provider when the returned page is completed, after which GET api/2.0/portal/payment/customerinfo reports it as set. The URL is absolute, carries the caller's e-mail, the language of the request and the currency of the region, and redirects to successUrl or backUrl when the user finishes or cancels. It buys nothing - a plan is bought with PUT api/2.0/portal/payment/url.

Parameters

Name	In	Type	Description	Notes
BackUrl	query	URI (uri)	The absolute address the setup page sends the user back to when attaching a payment method is abandoned. It has to be a well-formed URL and must be reachable by that user rather than by the portal.	[required] [example: `https://example.com/payment/back`] [minLength: 0] [maxLength: 255]
SuccessUrl	query	URI (uri)	The absolute address the setup page sends the user to once the payment provider has stored the payment method. Reaching it means a method is now on file, which `GET api/2.0/portal/payment/customerinfo` confirms; nothing has been charged.	[required] [example: `https://example.com/payment/success`] [minLength: 0] [maxLength: 255]

Responses

Status code	Description	Type	Response headers
200	The absolute URL of the payment method setup page, or an empty result when the portal already has a payment method	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator or, once a billing customer exists, not its payer; or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CustomerMonthlyUsageArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerBalance

BalanceWrapper getCustomerBalance(refresh)

GET /api/2.0/portal/payment/customer/balance

Get the customer balance

Returns the money the portal has in its wallet as the accounting service holds it: the account with its own currency, one sub-account per currency with the amount on it, and the most recent credit movement. Only a DocSpace administrator may read it, an installation without a billing service answers 403, and a portal that has never been a customer gets an empty result. The call is read-only. This balance is what the wallet services are charged against, so it falls as they are used and rises with POST api/2.0/portal/payment/deposit; the movements behind a change are listed by GET api/2.0/portal/payment/customer/operations. Pass refresh=true to re-read it from the accounting service rather than the cache - right after a top-up the cached figure is still the old one.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Whether the answer is fetched from the billing service instead of the portal cache. The cached copy is what a start-up needs and costs nothing; asking for a fresh one makes a remote call, so use it right after a purchase or a top-up and not on every read.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The wallet account with its sub-account per currency, or an empty result when the portal has no billing customer	BalanceWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

BalanceWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerInfo

CustomerInfoWrapper getCustomerInfo(refresh)

GET /api/2.0/portal/payment/customerinfo

Get the customer information

Returns the billing customer behind the portal: the e-mail its billing account is registered to, whether a payment method is stored for it, and the portal user who is the payer of that account. Only a DocSpace administrator may read it, and the call is read-only. The answer is empty in two ordinary cases - the installation has no billing service configured at all, and the portal has never been a customer - so an empty body is not an error. payer is filled in only when the billing e-mail belongs to a portal user; when it does not, the e-mail is still shown but the field stays empty, and that is what makes every payer-only operation of this group unreachable for everybody. refresh=true re-reads the customer from the billing provider instead of the cache, which is worth doing right after a payment method has been attached.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Whether the answer is fetched from the billing service instead of the portal cache. The cached copy is what a start-up needs and costs nothing; asking for a fresh one makes a remote call, so use it right after a purchase or a top-up and not on every read.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The billing customer with its payer, or an empty result when the portal has no customer or billing is not configured	CustomerInfoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CustomerInfoWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerMonthlyUsage

CustomerMonthlyUsageArrayWrapper getCustomerMonthlyUsage(startDate, endDate)

GET /api/2.0/portal/payment/customer/usage/monthly

Get the customer monthly usage

Returns what the portal spent from its wallet added up per calendar month, so a client can draw a spending chart without paging through every movement. Only a DocSpace administrator may read it, a portal with no billing customer answers with an empty result, and the call is read-only. startDate and endDate bound the period, both inclusive, and default to the portal creation date and the present moment; the months are cut in the portal time zone, so a movement at the edge of a month falls where the portal sees it and not where UTC does. Each item names its year and month, the total charged in it with the currency, and how many operations that total came from. The movements behind a month are in GET api/2.0/portal/payment/customer/operations, and the same figures as a file come from POST api/2.0/portal/payment/customer/usage/monthly/report.

Parameters

Name	In	Type	Description	Notes
startDate	query	Date (date-time)	The beginning of the reported period, inclusive. The months are cut in the portal time zone rather than in UTC, so spending at the turn of a month falls where the portal sees it; defaults to the portal creation date.	[optional] [example: `2025-01-01T00:00:00Z`]
endDate	query	Date (date-time)	The end of the reported period, inclusive. Cut in the portal time zone in the same way as `startDate`, and defaults to the moment the call is made.	[optional] [example: `2025-12-31T23:59:59Z`]

Responses

Status code	Description	Type	Response headers
200	One item per calendar month that had spending, or an empty result when the portal has no billing customer	CustomerMonthlyUsageArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerMonthlyUsageReport

DocumentBuilderTaskWrapper getCustomerMonthlyUsageReport()

GET /api/2.0/portal/payment/customer/usage/monthly/report

Get the monthly usage report status

Returns the state of the xlsx monthly usage report this user started with POST api/2.0/portal/payment/customer/usage/monthly/report: percentage while it is being built, isCompleted when it is done, resultFileId, resultFileName and resultFileUrl pointing at the file in the caller's My documents, and error when the build failed. The portal needs a billing customer and the caller has to be a DocSpace administrator; the call is read-only and is the one to poll. The task is kept per user and per report kind, so it reports neither another administrator's report nor the operations and service usage ones, which have their own status operations. An empty result means this user has no monthly usage report at all - none was started, or the finished one was already picked up or terminated. A completed task is dropped as soon as the next report is started, so read the file link out of the same answer that first reports isCompleted.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of this user's monthly usage report, or an empty result when there is none	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerOperations

ReportWrapper getCustomerOperations(offset, limit, ServiceName, StartDate, EndDate, ParticipantName, Credit, Debit, Type, Status, OrderBy, OrderType)

GET /api/2.0/portal/payment/customer/operations

Get the wallet operations

Lists the money movements on the portal's wallet - top-ups, the charges of the wallet services, refunds and corrections - one page at a time, which is what a billing history is built from. Only a DocSpace administrator may read it, a portal with no billing customer answers with an empty result, and the call is read-only. Every filter is optional: startDate and endDate are read in the portal time zone and default to the portal creation date and the present moment, serviceName narrows to particular wallet services and fails with 404 on a name this installation does not sell, participantName, type and status narrow to who caused a movement and how it ended, and credit and debit include or exclude the two directions. offset and limit page through the result and default to 0 and 25, orderBy and orderType sort it, and the answer repeats them next to totalQuantity, totalPage and currentPage so a client can page without counting. The same data as a downloadable file is POST api/2.0/portal/payment/customer/operationsreport, and the figures added up per service are GET api/2.0/portal/payment/customer/usage.

Parameters

Name	In	Type	Description	Notes
offset	query	Integer (int32)	The number of movements to skip before the first one returned, for walking through a long history page by page. Counted after the filters and the ordering are applied, and starts at 0 when omitted.	[optional] [example: `0`]
limit	query	Integer (int32)	The maximum number of movements returned in one page. Defaults to 25 when omitted; the answer echoes the window back next to `totalQuantity`, `totalPage` and `currentPage`, so the next `offset` can be computed without counting the items.	[optional] [example: `25`]
ServiceName	query	List	The wallet services whose movements are kept, named the way the billing catalogue names them - `backup`, `ai-tools`, `ai-search`, `disk-storage`, `docscloud`. Take the values from the `serviceName` field of `GET api/2.0/portal/payment/walletservices`; the match ignores case, a name this installation does not sell fails the call with 404, and an omitted list keeps every service. A bare string is accepted in place of an array for backward compatibility.	[optional] [example: `[backup]`]
StartDate	query	Date (date-time)	The beginning of the reported period, inclusive. Read in the portal time zone rather than in UTC, so a movement at the edge of the period falls where the portal sees it; defaults to the portal creation date.	[optional] [example: `2024-01-01T00:00:00Z`]
EndDate	query	Date (date-time)	The end of the reported period, inclusive. Read in the portal time zone rather than in UTC, and defaults to the moment the call is made.	[optional] [example: `2024-01-31T23:59:59Z`]
ParticipantName	query	String	The participant whose movements are kept - the account the accounting service records as the cause of a movement. A movement caused by a portal user carries that user ID here, and one caused by the portal itself carries the customer name; surrounding whitespace is trimmed, and an omitted value keeps every participant.	[optional] [example: `My Own Corporation`]
Credit	query	Boolean	Whether movements that add money to the wallet - top-ups, refunds and corrections in the portal's favour - are kept. Both directions are reported when neither this nor `debit` is given.	[optional] [example: `true`]
Debit	query	Boolean	Whether movements that take money out of the wallet - the charges of the wallet services - are kept. Both directions are reported when neither this nor `credit` is given.	[optional] [example: `false`]
Type	query	OperationType	The kind of movement to keep, which says what caused the money to move rather than how it ended. Every kind is reported when it is omitted.	[optional] [example: `ServicePayment`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`]
Status	query	OperationStatus	The outcome to keep. A movement that is still being settled is reported as pending and may change later, while the other outcomes are final; every outcome is reported when this is omitted.	[optional] [example: `Completed`] [enum: `0`, `1`, `2`, `3`]
OrderBy	query	String	The name of the field the movements are sorted by, spelled as the accounting service names it, such as `StartDate` or `ServiceName`. Surrounding whitespace is trimmed, and the accounting service applies its own ordering when this is omitted.	[optional] [example: `StartDate`]
OrderType	query	OperationOrderType	The direction the field named in `orderBy` is sorted in. Newest or largest first is what the accounting service does by default, so leaving this out sorts the same way as asking for descending explicitly.	[optional] [example: `Descending`] [enum: `0`, `1`]

Responses

Status code	Description	Type	Response headers
200	A page of wallet movements with its paging information, or an empty result when the portal has no billing customer	ReportWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	One of the names in `serviceName` is not a wallet service of this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ReportWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerOperationsReport

DocumentBuilderTaskWrapper getCustomerOperationsReport()

GET /api/2.0/portal/payment/customer/operationsreport

Get the operations report status

Returns the state of the xlsx wallet operations report this user started with POST api/2.0/portal/payment/customer/operationsreport: percentage while it is being built, isCompleted when it is done, resultFileId, resultFileName and resultFileUrl pointing at the file in the caller's My documents, and error when the build failed. The portal needs a billing customer and the caller has to be a DocSpace administrator; the call is read-only and is the one to poll. The task is kept per user and per report kind, so it never reports another administrator's report, nor the service usage and monthly usage ones, which have their own status operations. An empty result means this user has no operations report at all - none was started, or the finished one was already picked up or terminated. A completed task is dropped as soon as the next report is started, so read the file link out of the same answer that first reports isCompleted.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of this user's operations report, or an empty result when there is none	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CustomerServiceUsageReportWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerServiceUsage

CustomerServiceUsageReportWrapper getCustomerServiceUsage(ServiceName, ParticipantName, Status, StartDate, EndDate, Metadata, offset, limit, OrderBy, OrderType)

GET /api/2.0/portal/payment/customer/usage

Get the customer service usage

Returns how much of each wallet service the portal consumed and what that cost, added up per service instead of listed per movement. Only a DocSpace administrator may read it, a portal with no billing customer answers with an empty result, and the call is read-only. The filters are optional: serviceName narrows to particular services and fails with 404 on a name this installation does not sell, participantName and status narrow to who consumed and how the operation ended, startDate and endDate bound the period in the portal time zone, metadata matches the key and value pairs a service records with its usage, and offset, limit, orderBy and orderType page and sort the result. Amounts come with the unit the service is sold in, except AI tools, whose consumption is reported in tokens rather than in AI credits. The individual charges behind these totals are GET api/2.0/portal/payment/customer/operations, and the same figures as a downloadable file are POST api/2.0/portal/payment/customer/usage/report.

Parameters

Name	In	Type	Description	Notes
ServiceName	query	List	The wallet services whose consumption is added up, named the way the billing catalogue names them - `backup`, `ai-tools`, `ai-search`, `disk-storage`, `docscloud`. Take the values from the `serviceName` field of `GET api/2.0/portal/payment/walletservices`; the match ignores case, a name this installation does not sell fails the call with 404, and an omitted list covers every service.	[optional] [example: `[backup]`]
ParticipantName	query	String	The participant whose consumption is added up - the account the accounting service records as the consumer. Consumption caused by a portal user carries that user ID here; surrounding whitespace is trimmed, and an omitted value covers every participant.	[optional] [example: `My Own Corporation`]
Status	query	OperationStatus	The outcome to keep. Consumption that is still being settled is reported as pending and may change later, while the other outcomes are final; every outcome is counted when this is omitted.	[optional] [example: `Completed`] [enum: `0`, `1`, `2`, `3`]
StartDate	query	Date (date-time)	The beginning of the reported period, inclusive. Read in the portal time zone rather than in UTC, and defaults to the portal creation date.	[optional] [example: `2025-01-01T00:00:00Z`]
EndDate	query	Date (date-time)	The end of the reported period, inclusive. Read in the portal time zone rather than in UTC, and defaults to the moment the call is made.	[optional] [example: `2025-12-31T23:59:59Z`]
Metadata	query	Map	The usage annotations a wallet service records alongside its consumption, as the key and value pairs that must all match for a record to be counted. The keys are chosen by the service that writes them, so read them off the `metadata` of the records already returned rather than guessing; an omitted map counts every record.	[optional] [example: `{"key1":"value1","key2":"value2"}`]
offset	query	Integer (int32)	The number of per-service totals to skip before the first one returned. Counted after the filters and the ordering are applied, and starts at 0 when omitted.	[optional] [example: `0`]
limit	query	Integer (int32)	The maximum number of per-service totals returned in one page. Defaults to 25 when omitted; the answer echoes the window back with its paging information, so the next `offset` can be computed without counting the items.	[optional] [example: `25`]
OrderBy	query	String	The name of the field the per-service totals are sorted by, spelled as the accounting service names it, such as `ServiceName` or `StartDate`. Surrounding whitespace is trimmed, and the accounting service applies its own ordering when this is omitted.	[optional] [example: `ServiceName`]
OrderType	query	OperationOrderType	The direction the field named in `orderBy` is sorted in. Newest or largest first is what the accounting service does by default, so leaving this out sorts the same way as asking for descending explicitly.	[optional] [example: `Descending`] [enum: `0`, `1`]

Responses

Status code	Description	Type	Response headers
200	The usage and cost per wallet service with its paging information, or an empty result when the portal has no billing customer	CustomerServiceUsageReportWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	One of the names in `serviceName` is not a wallet service of this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCustomerServiceUsageReport

DocumentBuilderTaskWrapper getCustomerServiceUsageReport()

GET /api/2.0/portal/payment/customer/usage/report

Get the service usage report status

Returns the state of the xlsx service usage report this user started with POST api/2.0/portal/payment/customer/usage/report: percentage while it is being built, isCompleted when it is done, resultFileId, resultFileName and resultFileUrl pointing at the file in the caller's My documents, and error when the build failed. The portal needs a billing customer and the caller has to be a DocSpace administrator; the call is read-only and is the one to poll. The task is kept per user and per report kind, so it reports neither another administrator's report nor the operations and monthly usage ones, which have their own status operations. An empty result means this user has no service usage report at all - none was started, or the finished one was already picked up or terminated. A completed task is dropped as soon as the next report is started, so read the file link out of the same answer that first reports isCompleted.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of this user's service usage report, or an empty result when there is none	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPaymentAccount

StringWrapper getPaymentAccount(backUrl)

GET /api/2.0/portal/payment/account

Get the billing account page

Hands back the address of the portal page on which the billing account is managed - the payment method on file, the invoices and the receipts - so a client can link to it instead of assembling the address itself. The portal must already have a billing customer: one that has never had it gets an empty result, and an installation without a billing service answers 403. Only the payer or the portal owner may read it, and the call changes nothing. The value is relative to the portal root (payment.ashx), and the optional backUrl is appended to it as a query parameter so the page can send the user back where they came from. It is not a checkout page: a plan is bought with PUT api/2.0/portal/payment/url and a payment method is attached with GET api/2.0/portal/payment/checkoutsetupurl.

Parameters

Name	In	Type	Description	Notes
backUrl	query	URI (uri)	The absolute address the billing account page should offer as its way back. It is appended to the returned portal-relative address as a query parameter rather than followed here, and omitting it yields the bare address of the page.	[optional] [example: `https://example.com`] [minLength: 0] [maxLength: 255]

Responses

Status code	Description	Type	Response headers
200	The portal-relative address of the billing account page, or an empty result when the portal has no billing customer	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is neither the payer nor the portal owner, or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CurrenciesArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPaymentCurrencies

CurrenciesArrayWrapper getPaymentCurrencies()

GET /api/2.0/portal/payment/currencies

Get the billing currencies

Tells a client which currency the portal is billed in: the default currency of the portal region always comes first, followed by the currency resolved for the current request when that one differs, so the answer holds one or two items. Nothing has to be called first, the caller needs the permission to edit the portal settings, and the call is read-only. Each item carries the country code of the region, the currency symbol and the native name of the currency; the first item is the currency the amounts from GET api/2.0/portal/payment/prices are expressed in. These are the currencies of the subscription prices, and they are not the accounting currencies the wallet is topped up in - those come with the balance in GET api/2.0/portal/payment/customer/balance.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The default currency of the portal region first, followed by the currency of the current request when it differs	CurrenciesArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPaymentQuotas

QuotaArrayWrapper getPaymentQuotas(wallet, additional)

GET /api/2.0/portal/payment/quotas

Get the purchasable quotas

Lists the quotas the portal can be put on - the paid plans and the wallet services - each with its price, its features and the limits it grants, which is what a pricing page is built from. Nothing has to be called first, the caller needs the permission to edit the portal settings, and the call is read-only. Only quotas marked visible are listed, newest first, and the two optional filters narrow that: wallet selects the wallet services (true) or the subscription plans (false), additional selects the add-ons to a plan (true) or the plans themselves (false), and an omitted filter keeps both kinds. A portal on a non-profit quota is a special case - asking for additional=false returns that single quota and nothing else, because no other plan may be bought for it. The quota the portal is actually on is not marked here; read it from GET api/2.0/portal/payment/quota.

Parameters

Name	In	Type	Description	Notes
wallet	query	Boolean	Which side of the catalogue is listed: `true` keeps the services paid out of the portal wallet, `false` keeps the subscription plans, and omitting it keeps both.	[optional] [example: `true`]
additional	query	Boolean	Which layer of the catalogue is listed: `true` keeps the add-ons that extend a plan, `false` keeps the plans themselves, and omitting it keeps both.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The visible quotas matching the filters, newest first, each with its price, features and limits	QuotaArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

QuotaArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPaymentUrl

StringWrapper getPaymentUrl(PaymentUrlRequestDto)

PUT /api/2.0/portal/payment/url

Get the payment page URL

Starts the purchase of a monthly paid plan for this portal by handing back the hosted checkout page the buyer has to open; nothing is bought until that page is completed. The portal must have no paid plan yet - a portal whose plan is already paid gets an empty result and changes its subscription through PUT api/2.0/portal/payment/update instead - and the product name in quantity must be one of the monthly, non-wallet plans listed by GET api/2.0/portal/payment/quotas. Only a DocSpace administrator may call it. The call itself changes nothing on the portal and may be repeated: the money is taken by the payment provider on the checkout page, and the plan becomes active once the provider confirms it. The returned URL is absolute and single-purpose - it carries the caller's e-mail, the language of the request and the currency of the request region, and it redirects to successUrl or backUrl when the buyer finishes or cancels. Exactly one product per call is accepted and its quantity has to be greater than zero; yearly and wallet products are refused, and wallet services are bought with PUT api/2.0/portal/payment/updatewallet instead.

Parameters

Name	In	Type	Description	Notes
PaymentUrlRequestDto	body	PaymentUrlRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The absolute URL of the checkout page to open, or an empty result when the portal already has a paid plan	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	`quantity` holds more than one product, a quantity that is not greater than zero, or a product that is not a monthly plan	-	-
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

getPortalPrices_200_response

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getPortalPrices

getPortalPrices_200_response getPortalPrices()

GET /api/2.0/portal/payment/prices

Get the product prices

Lists what one unit of every purchasable product costs, keyed by the product name that quantity takes in the purchase operations, so a client can price a plan or a wallet service without reading the whole quota list. Nothing has to be called first, and the caller needs the permission to edit the portal settings, which portal administrators and the owner have. The call is read-only. Prices are given in the one currency resolved for this request from the portal region, which GET api/2.0/portal/payment/currencies reports; a product with no price in that currency comes back as 0 rather than being left out, so a zero means unpriced and not free. The list covers the products on offer, not the portal's own plan - the plan in force, with its limits and its usage, is GET api/2.0/portal/payment/quota.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Product name to the price of one unit in the currency of the request, `0` where the product has no price in it	getPortalPrices_200_response	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getQuotaPaymentInformation

QuotaWrapper getQuotaPaymentInformation(refresh)

GET /api/2.0/portal/payment/quota

Get the current plan and limits

Returns the quota the portal is on right now - its paid plan or the free one - with everything a client needs to render itself: the price, the features that are switched on, the limits they grant (rooms, storage in bytes, users, administrators, AI) and how much of each is already used. Every signed-in member of the portal reads it, so it is not restricted to administrators; only guests are refused with 403. The call is read-only. The plan is served from the cache by default, which is what a start-up needs; refresh=true fetches it from the billing service instead, so use that right after a purchase and not routinely, because it is a remote call. The catalogue of the quotas that could be bought instead is GET api/2.0/portal/payment/quotas, and the money side of the same portal - customer, wallet and balance - starts at GET api/2.0/portal/payment/customerinfo.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Whether the answer is fetched from the billing service instead of the portal cache. The cached copy is what a start-up needs and costs nothing; asking for a fresh one makes a remote call, so use it right after a purchase or a top-up and not on every read.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The quota the portal is on, with its price, features, limits and current usage	QuotaWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is a guest of this portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

QuotaWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRestrictedAiModels

RestrictedModelsResponseWrapper getRestrictedAiModels()

GET /api/2.0/portal/payment/ai-model/restrictions

Get restricted AI models

Returns the AI chat models that are barred on this portal - the ones no user of it may pick for a conversation, whatever the price list offers. Only a DocSpace administrator may read it, and the call is read-only. When the installation has no billing service or AI is not enabled for the portal, the answer is an empty set instead of an error, which is indistinguishable from a portal that restricts nothing. An empty models therefore means every model in GET api/2.0/portal/payment/ai-prices may be used. The set names the barred models and not the allowed ones; replace it with PUT api/2.0/portal/payment/ai-model/restrictions.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The identifiers of the AI chat models barred on this portal, empty when none is	RestrictedModelsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

RestrictedModelsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSubscriptionBalanceInfo

SubscriptionBalanceInfoWrapper getSubscriptionBalanceInfo()

GET /api/2.0/portal/payment/subscription/balance

Get the subscription balance information

Reports in money how much of the portal's paid subscription period is still unused - the credit that POST api/2.0/portal/payment/subscription/movetowallet would carry over to the wallet if the subscription were ended now. The portal must have a billing customer and a plan in the paid state; a plan that is not paid answers 402, and a paid plan without a subscription row gives 404. Only the payer - the portal user whose e-mail is the billing customer's e-mail - may read it, and the call is read-only. The answer states the total cost of the current period with its currency, the start and the end of that period in UTC, the moment the unused part is measured up to, the days already elapsed, and the remaining balance both in the subscription currency and converted to the wallet currency. Every figure is computed for the instant of the request, so it changes between calls.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The unused balance of the current subscription period with its period boundaries and currencies	SubscriptionBalanceInfoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The plan currently paid is a wallet product or has no product identifier	-	-
402	The plan of the portal is not in the paid state	-	-
403	The caller is not the payer of this portal, or the portal has no billing service configured	-	-
404	This portal has no billing customer, or its paid plan has no subscription	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SubscriptionBalanceInfoWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantWalletServiceSettings

TenantWalletServiceSettingsWrapper getTenantWalletServiceSettings()

GET /api/2.0/portal/payment/servicessettings

Get the wallet service settings

Returns which wallet services an administrator has switched on for this portal by hand, as opposed to the ones its plan pays for. Only a DocSpace administrator may read it, an installation without a billing service answers 403, no billing customer is needed, and the call is read-only. enabledServices holds the names of those services and is empty when none was switched on. This is the stored setting and not the state of the portal: a service the plan brings with it is active without appearing here, so the honest answer to what is running is GET api/2.0/portal/payment/activeservices. One entry is changed with POST api/2.0/portal/payment/servicestate.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The wallet services switched on by hand for this portal	TenantWalletServiceSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantWalletServiceSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantWalletSettings

TenantWalletSettingsResponseWrapper getTenantWalletSettings()

GET /api/2.0/portal/payment/topupsettings

Get the auto top-up settings

Returns the portal's automatic wallet top-up settings - whether it is on, the balance that triggers a charge, the balance it is topped up to, and the currency both are expressed in. Any DocSpace administrator may read them, and unlike the operation that changes them this one needs neither a billing customer nor a configured billing service, so it answers on a portal that has never paid for anything. It is read-only and changes nothing. A portal that has never configured top-up gets the defaults rather than an empty result: enabled is false, currency is null, and minBalance and upToBalance are 0. Those two zeros are outside the ranges POST api/2.0/portal/payment/topupsettings accepts - 5 to 1000 and 6 to 5000 - so the answer cannot be sent straight back to it; supply real values instead. lastModified is 0001-01-01T00:00:00 until the settings are stored for the first time. lowBalanceThreshold and lowBalanceNotified are maintained by the portal itself: they are reported here, but ignored when the settings are written.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The automatic top-up settings of the portal, or their defaults when it has never configured them	TenantWalletSettingsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantWalletSettingsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWalletService

WalletServiceWrapper getWalletService(service)

GET /api/2.0/portal/payment/walletservice

Get a wallet service

Returns one wallet service by name, for a client that already knows which service it needs and does not want the whole catalogue. service is the name of the service - Storage, Backup, AITools, Admin, DocsCloud, DocsCloudDevPack or AISearch - and a name this installation does not sell answers 404. Nothing has to be called first, the caller needs the permission to edit the portal settings, and the call is read-only. The answer has the same shape as one item of GET api/2.0/portal/payment/walletservices - the price of a unit, the unit, the limits the service grants and its service name - except that the variants of a service are not grouped into innerServices here, because a single service is looked up directly. The price is in the currency resolved for the request.

Parameters

Name	In	Type	Description	Notes
service	query	TenantWalletService	The service to look up, given by its catalogue name. A service this installation does not sell answers 404, and the whole catalogue is `GET api/2.0/portal/payment/walletservices`.	[required] [example: `Storage`] [enum: `-18`, `-16`, `-15`, `-14`, `-13`, `-12`, `-11`]

Responses

Status code	Description	Type	Response headers
200	The wallet service with its price, unit and the limits it grants	WalletServiceWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings	-	-
404	This installation does not sell a wallet service under that name	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WalletServiceWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWalletServices

WalletServiceArrayWrapper getWalletServices()

GET /api/2.0/portal/payment/walletservices

Get wallet services

Lists every service the portal may pay for out of its wallet - extra administrators, disk storage, backup, AI tools, AI search and Docs Connect - with the price of a unit, the unit it is sold in and whether the portal has it switched on. Nothing has to be called first, the caller needs the permission to edit the portal settings, and the call is read-only. Services that are variants of one another are folded together: the visible one carries the rest in its innerServices, so a client renders one card per group. The AI services are left out entirely when AI is not enabled for the portal. This is the catalogue and not the state of the portal - what is actually running is GET api/2.0/portal/payment/activeservices, one service on its own is GET api/2.0/portal/payment/walletservice, and switching one on or off is POST api/2.0/portal/payment/servicestate.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The wallet services on offer, with their prices, units and grouped variants	WalletServiceArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WalletServiceArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

moveSubscriptionToWallet

BooleanWrapper moveSubscriptionToWallet(QuantityRequestDto)

POST /api/2.0/portal/payment/subscription/movetowallet

Move the subscription to the wallet

Ends the portal's paid subscription and moves it onto the wallet: the unused balance of the running period is credited to the wallet, the wallet is topped up from the payment method on file if that credit does not cover the purchase, and the requested number of administrators is then bought as a wallet service. The portal needs a billing customer with a payment method set and a plan in the paid state, quantity has to name the administrators wallet product, and the number asked for may not be below the administrators the portal already has - read the credit that will be carried over from GET api/2.0/portal/payment/subscription/balance first. Only the payer may call it. The call is mutating, spends money and cannot be undone: the subscription is ended before the purchase is attempted, so a failure in the second half leaves the portal on the wallet with the money credited but the administrators unbought, and a repeat would then buy them a second time. It is limited to ten requests a minute per user by default. The result is true when the administrators were bought.

Parameters

Name	In	Type	Description	Notes
QuantityRequestDto	body	QuantityRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	`true` when the balance was moved to the wallet and the administrators were bought	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	`quantity` does not name the administrators wallet product, or the number asked for is below the administrators the portal already has	-	-
402	The plan of the portal is not paid, the balance could not be moved, or the wallet is still short of the price after the top-up	-	-
403	The caller is not the payer of this portal, the portal has no billing service configured, or the customer has no payment method set	-	-
404	This portal has no billing customer, its paid plan has no subscription, or the price of the administrators product is unknown	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

RestrictedModelsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

sendPaymentRequest

sendPaymentRequest(SalesRequestsDto)

POST /api/2.0/portal/payment/request

Contact the sales team

Sends the portal's message to the ONLYOFFICE sales team - the contact-sales form behind a request for a quote, an invoice or a plan that cannot be bought online. email has to be a well-formed address and is where the answer will go, while userName and message say who is asking and what for; all three are required and none may be empty. Only a DocSpace administrator may call it. Nothing on the portal changes: no plan, no quota and no payment is touched, a message is mailed out and the request is written to the portal audit trail. There is no response body - status 200 means the message was handed to the mail service - and the call is not idempotent, so a repeat sends a second message. It is limited to ten requests a minute per user by default and answers 429 above that.

Parameters

Name	In	Type	Description	Notes
SalesRequestsDto	body	SalesRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The message has been handed to the mail service; the response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	`email` is not a well-formed address, or one of the required fields is empty	-	-
403	The caller is not a DocSpace administrator	-	-
429	This user has made more than ten requests in a minute	ErrorApiResponse	`Retry-After`
401	Unauthorized	ErrorApiResponse	-
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setRestrictedAiModels

RestrictedModelsResponseWrapper setRestrictedAiModels(SetRestrictedAiModelsRequestDto)

PUT /api/2.0/portal/payment/ai-model/restrictions

Set restricted AI models

Replaces the whole set of AI chat models barred on this portal: the body is the complete set that is to hold, so adding one restriction means sending the new model together with the ones already restricted, lifting one means leaving it out, and an empty set lifts them all. Read the current set from GET api/2.0/portal/payment/ai-model/restrictions and the model identifiers from GET api/2.0/portal/payment/ai-prices before calling. The installation needs a billing service and the AI gateway configured, the portal needs a billing customer, and the caller needs the permission to edit the portal settings as well as DocSpace administrator rights. The call is mutating and idempotent - sending the same set twice leaves the same state - and it is written to the portal audit trail. It takes effect on the next AI request, so a conversation already open on a model that has just been barred cannot go on with it. The stored set comes back in the answer.

Parameters

Name	In	Type	Description	Notes
SetRestrictedAiModelsRequestDto	body	SetRestrictedAiModelsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The set of barred AI chat models as it was stored	RestrictedModelsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit the portal settings or is not a DocSpace administrator, or the installation has no billing service or no AI gateway configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setTenantWalletSettings

TenantWalletSettingsResponseWrapper setTenantWalletSettings(TenantWalletSettingsWrapper)

POST /api/2.0/portal/payment/topupsettings

Set the auto top-up settings

Switches the portal's automatic wallet top-up on or off and sets its thresholds: while it is on, the payment method on file is charged whenever the wallet balance falls below minBalance, enough to bring it up to upToBalance, in currency. The portal needs a billing customer whose wallet balance exists - a portal that has never had one answers 404, so top the wallet up once with POST api/2.0/portal/payment/deposit first - and only the payer may change the settings. The body replaces the stored settings as a whole and an omitted body resets them to the defaults; minBalance is accepted between 5 and 1000 and upToBalance between 6 and 5000, while lowBalanceThreshold and lowBalanceNotified are ignored on the way in and kept as the portal had them. The call is mutating and idempotent, it charges nothing by itself, it is written to the portal audit trail, and switching the top-up on also re-arms the low-balance warning. The settings as they were stored come back in the answer.

Parameters

Name	In	Type	Description	Notes
TenantWalletSettingsWrapper	body	TenantWalletSettingsWrapper		[optional]

Responses

Status code	Description	Type	Response headers
200	The automatic top-up settings as they were stored	TenantWalletSettingsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not the payer of this portal, or the portal has no billing service configured	-	-
404	This portal has no billing customer, or its wallet has no balance yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantWalletSettingsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

terminateCustomerMonthlyUsageReport

terminateCustomerMonthlyUsageReport()

DELETE /api/2.0/portal/payment/customer/usage/monthly/report

Terminate the monthly usage report

Stops the xlsx monthly usage report this user has running and drops its task, for a report that was started for the wrong period or is no longer wanted. The portal needs a billing customer and the caller has to be a DocSpace administrator. The stop is asked of the worker that builds the file rather than done here, so GET api/2.0/portal/payment/customer/usage/monthly/report can still answer for a moment afterwards. The call is safe to repeat and does nothing at all when this user has no such report running: there is no response body, and status 200 says the stop was requested, not that a report was really stopped. It leaves the operations and service usage reports alone, and a report that had already finished keeps its file in My documents.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The stop has been requested; the response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

terminateCustomerOperationsReport

terminateCustomerOperationsReport()

DELETE /api/2.0/portal/payment/customer/operationsreport

Terminate the operations report

Stops the xlsx wallet operations report this user has running and drops its task, for a report that was started with the wrong filters or is no longer wanted. The portal needs a billing customer and the caller has to be a DocSpace administrator. The stop is asked of the worker that builds the file rather than done here, so GET api/2.0/portal/payment/customer/operationsreport can still answer for a moment afterwards. The call is safe to repeat and does nothing at all when this user has no report running: there is no response body, and status 200 says the stop was requested, not that a report was really stopped. A report that had already finished keeps its file in My documents - nothing is deleted from there.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The stop has been requested; the response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

terminateCustomerServiceUsageReport

terminateCustomerServiceUsageReport()

DELETE /api/2.0/portal/payment/customer/usage/report

Terminate the service usage report

Stops the xlsx service usage report this user has running and drops its task, for a report that was started with the wrong filters or is no longer wanted. The portal needs a billing customer and the caller has to be a DocSpace administrator. The stop is asked of the worker that builds the file rather than done here, so GET api/2.0/portal/payment/customer/usage/report can still answer for a moment afterwards. The call is safe to repeat and does nothing at all when this user has no such report running: there is no response body, and status 200 says the stop was requested, not that a report was really stopped. It leaves the operations and monthly usage reports alone, and a report that had already finished keeps its file in My documents.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The stop has been requested; the response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

topUpDeposit

BooleanWrapper topUpDeposit(TopUpDepositRequestDto)

POST /api/2.0/portal/payment/deposit

Top up the wallet

Charges the payment method on file and adds the amount to the portal's wallet, the balance every wallet service is paid from. The portal needs a billing customer with a payment method set - attach one with GET api/2.0/portal/payment/checkoutsetupurl - currency has to be one of the accounting currencies this installation supports, and amount is a whole number of currency units between 1 and 999999. Only the payer may call it. The call takes money and is not idempotent in any way: two identical requests charge twice, so a client must not retry it blindly after a timeout, and it is limited to ten requests a minute per user by default. A successful top-up pushes the new balance to the portal clients over their socket connection and re-arms the low-balance notification. The result is true when the payment provider accepted the charge; read the resulting balance back from GET api/2.0/portal/payment/customer/balance.

Parameters

Name	In	Type	Description	Notes
TopUpDepositRequestDto	body	TopUpDepositRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	`true` when the payment provider accepted the charge and the wallet was credited	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	`currency` is not one of the supported accounting currencies, or `amount` is outside 1 to 999999	-	-
403	The caller is not the payer of this portal, the portal has no billing service configured, or the customer has no payment method set	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updatePayment

BooleanWrapper updatePayment(QuantityRequestDto)

PUT /api/2.0/portal/payment/update

Change the subscription quantity

Changes how many units of the plan the portal is paying for - the number of administrators it covers - and lets the payment provider bill the difference against the payment method already on file. The portal must have a billing customer and a plan bought through PUT api/2.0/portal/payment/url, and while the portal is on a priced plan the product name in quantity has to be that same plan, which GET api/2.0/portal/payment/quota reports, because a subscription is changed here and not swapped. Only the payer - the portal user whose e-mail is the billing customer's e-mail - may call it. The call is mutating and charges money, and it is guarded against a double submission: once the new quantity is in effect, repeating the same request fails with 400 because that quantity is already set. The result is true when the provider accepted the change and false when it declined it without an error. Exactly one product per call is accepted, the operation is limited to ten requests a minute per user by default and answers 429 above that, and wallet services are not bought here - use PUT api/2.0/portal/payment/updatewallet for those.

Parameters

Name	In	Type	Description	Notes
QuantityRequestDto	body	QuantityRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	`true` when the provider accepted the new quantity, `false` when it declined it	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The product is not the plan currently paid, or the quantity is already the one in effect	-	-
403	The caller is not the payer of this portal, or the portal has no billing service configured	-	-
404	This portal has no billing customer yet	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateWalletPayment

BooleanWrapper updateWalletPayment(WalletQuantityRequestDto)

PUT /api/2.0/portal/payment/updatewallet

Change a wallet service quantity

Buys more units of a wallet service - extra administrators, disk storage, backup, AI tools, AI search or Docs Connect - or writes down the quantity that service will have after the next renewal, depending on productQuantityType. With Add (1) the units are bought at once and paid out of the portal wallet, so the wallet needs a sub-account in the accounting currency and enough money on it; with Set (0) nothing is charged now and the quantity only takes effect in the next period, where an empty or zero quantity cancels a change scheduled earlier. Renew and Sub are not accepted here. The portal needs a billing customer and the caller has to be a DocSpace administrator; a service that is an add-on to the plan also needs the plan itself to be paid, otherwise the answer is 402. Minimum quantities apply - disk storage starts at 100 units, the Docs Connect Dev Pack at 10, and the administrators may not be fewer than the portal already has - and in the Add form they are checked only while the portal does not hold that service yet. Asking for the Docs Connect plan in the Set form while Docs Connect Dev Pack is active schedules the reversion to it at the next period, while the upgrade in the other direction is not done here at all: use POST api/2.0/settings/docscloud/switchtodevpack. The result is true when the change was accepted; the call is mutating, spends money in its Add form and is limited to ten requests a minute per user by default. Price the same purchase without paying for it with PUT api/2.0/portal/payment/calculatewallet.

Parameters

Name	In	Type	Description	Notes
WalletQuantityRequestDto	body	WalletQuantityRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	`true` when the purchase or the scheduled change was accepted, `false` when the provider declined it	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The quantity type is not `Set` or `Add`, the product is not a wallet service, the quantity is below the minimum for it, or that service is already set	-	-
402	The plan of the portal is not paid and the requested service is an add-on to it	-	-
403	The caller is not a DocSpace administrator, or the portal has no billing service configured	-	-
404	This portal has no billing customer, or its wallet has no sub-account in the accounting currency	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

UpcomingPaymentArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

PortalQuotaApi

getPortalQuota

TenantQuotaWrapper getPortalQuota()

GET /api/2.0/portal/quota

Get the portal quota

Returns the quota this portal runs on - the allowance its tariff grants: how many users and paid users it may have, how many rooms, the largest total and single-file size, the price of the quota and the feature flags that go with it. The caller needs the portal-settings right and gets 403 without it; the call is read-only and idempotent. Sizes are in bytes, and maxTotalSize comes back as 0 when the calling account's own role is user, rather than as the real allowance. This is what the portal is allowed, not what it consumes: the consumption is reported by GET api/2.0/portal/usedspace in gigabytes and by GET api/2.0/portal/userscount. The quotas the portal could move to are listed by GET api/2.0/portal/payment/quotas, and GET api/2.0/portal/quota/right picks the smallest of them that would still fit. A free or trial quota carries no price, and the billing state that goes with the quota - paid, in grace period or not paid - is read from GET api/2.0/portal/tariff.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The allowance the current tariff grants this portal, with sizes in bytes	TenantQuotaWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller has no portal-settings right	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantQuotaWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalTariff

TariffWrapper getPortalTariff(refresh)

GET /api/2.0/portal/tariff

Get the portal tariff

Returns the tariff this portal runs on: its state, the end of the current period and the quotas - the plan and its add-ons - it is made of. Nothing has to be called first, the call is read-only and idempotent, and it keeps answering while the portal's payment has lapsed, which is what a client needs in order to show a payment warning. How much of it is filled depends on the caller: every user gets state, which is Trial, Paid, Delay for the grace period after the due date, or NotPaid; a room or DocSpace administrator also gets dueDate and delayDueDate; and a caller with the portal-settings right additionally gets id, customerId, licenseDate, the openSource, enterprise and developer flags and quotas, each entry naming the quota, its quantity, its own due date and the quota it switches to next period. Dates are in the portal time zone. Pass refresh=true to re-read the tariff from the billing system instead of the portal cache - it is slower, so use it after a payment, not on every page. What the next period will cost is listed by GET api/2.0/portal/tariff/upcoming.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Whether the tariff is re-read from the billing system instead of the portal cache. The remote read is slower, so ask for it right after a payment and leave it off for ordinary page loads.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The tariff of this portal, filled as far as the rights of the caller allow	TariffWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TariffWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalUsedSpace

DoubleWrapper getPortalUsedSpace()

GET /api/2.0/portal/usedspace

Get the portal used space

Returns how much space the content of this portal occupies, in gigabytes rounded to two decimals, so a client can show the storage bar next to the allowance. The caller needs the portal-settings right and is refused without it; the call is read-only and idempotent. The number is added up from the storage counters the portal keeps per owner, which means content that belongs to no account - system data - is not part of it, and it is a plain number, not an object. The counters are maintained as files are written and removed, so the value is current but may lag a large operation that is still running. The allowance to compare it with is maxTotalSize from GET api/2.0/portal/quota, in bytes rather than gigabytes, and the smallest quota that would still fit the portal is suggested by GET api/2.0/portal/quota/right. This operation says nothing about which room or user the space belongs to - the per-user figures come from the People API.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The space the portal content occupies, in gigabytes rounded to two decimals	DoubleWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DoubleWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRightQuota

TenantQuotaWrapper getRightQuota()

GET /api/2.0/portal/quota/right

Get the recommended quota

Recommends the cheapest quota this portal could run on and still fit: the lowest-priced quota that is not billed yearly, whose user allowance is above the number of active accounts and whose storage allowance is above the space already used. The caller needs the portal-settings right and gets 403 without it. The call is read-only, idempotent and buys nothing - it only picks one quota out of those the portal may switch to, comparing them with the figures that GET api/2.0/portal/userscount and GET api/2.0/portal/usedspace report. The answer is a single quota in the same shape as GET api/2.0/portal/quota, with sizes in bytes; when no quota is large enough the answer is an empty body with 200 and not an error, so handle the empty result as nothing to recommend. Yearly quotas are left out by design, so the recommendation is always a monthly one - the full list to choose from comes from GET api/2.0/portal/payment/quotas, and the purchase itself is started with PUT api/2.0/portal/payment/url.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The cheapest monthly quota that would still fit this portal, or an empty body when none does	TenantQuotaWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller has no portal-settings right	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantQuotaWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getUpcomingPayments

UpcomingPaymentArrayWrapper getUpcomingPayments(refresh)

GET /api/2.0/portal/tariff/upcoming

Get upcoming payments

Lists what this portal will be charged next for the quotas of its current tariff - one entry per quota that is going to be billed, with the amount, the currency and the due date. The caller needs the portal-settings right and gets 403 without it; the call is read-only and idempotent and keeps answering while the portal's payment has lapsed. Only quotas that are really charged appear: an overdue quota is skipped, and so is a quota that has no price of its own, such as a trial or a free plan - which is why the list can come back empty on a portal that does have a tariff. When a switch to another quota is scheduled for the next period, the entry describes that next quota and its quantity, so id and name may differ from what GET api/2.0/portal/tariff reports for today. amount is the unit price multiplied by quantity, in the currency named by currency as an ISO 4217 code, dueDate is in the portal time zone, and wallet marks a service paid from the portal wallet instead of the subscription.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Whether the tariff is re-read from the billing system instead of the portal cache. The remote read is slower, so ask for it right after a payment and leave it off for ordinary page loads.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The charges the portal is going to be billed next, one entry per quota, empty when nothing is due	UpcomingPaymentArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller has no portal-settings right	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

PortalSettingsApi

continuePortal

continuePortal()

PUT /api/2.0/portal/continue

Restore a portal

Brings a deactivated portal back to the active state, so its users can sign in again and its domain serves the portal as before. It is reached only with the reactivation link that POST api/2.0/portal/suspend mails to the portal owner: that link authorizes the call in place of an authentication token, and no ordinary token is accepted here. The call is mutating and idempotent - it sets the status to active, re-applies the portal's Content Security Policy and refreshes its base domain, and a portal that is already active is simply left active. Nothing is returned in the body; read the result from status in GET api/2.0/portal. Deactivating the portal again means asking for a fresh letter with POST api/2.0/portal/suspend, because each link is issued for one operation. This operation cannot bring back a removed portal: the deletion behind DELETE api/2.0/portal/delete is final, and a removed portal has to be restored from a backup instead.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	OK	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

deletePortal

StringWrapper deletePortal()

DELETE /api/2.0/portal/delete

Delete a portal

Removes this portal for good: its rooms, files, accounts, settings and OAuth clients go with it and its domain stops serving the portal. It is reached only with the removal link that POST api/2.0/portal/delete mails to the portal owner - that link authorizes the call instead of an authentication token - and the owner is checked again here; on a server installation the last remaining space cannot be removed. The call is destructive and cannot be undone, and there is no restore operation, so take a backup with POST api/2.0/backup/startbackup first when the content still matters. It keeps working while the portal's payment has lapsed. Along the way the portal is dropped from the hosting cache, the owner is mailed a confirmation, the removal is written to the audit trail and, for a portal that was paying, the support team is notified as well. The answer is the absolute URL of the feedback form to send the departing owner to. To pause the portal instead of erasing it, use PUT api/2.0/portal/suspend.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The absolute URL of the feedback form to send the owner of the removed portal to	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalInformation

TenantWrapper getPortalInformation()

GET /api/2.0/portal

Get portal information

Returns the portal the request was addressed to - the tenant behind the current domain - with its name, alias, owner, language, time zone, industry, trusted-domain rules, version and creation date. Nothing has to be called first, the call is read-only and idempotent, and it keeps answering while the portal's payment has lapsed. What comes back depends on the caller's rights: a caller with the portal-settings right gets the whole record, while every other user gets an object in which only tenantId is filled and no error is raised - so check tenantAlias for null before reading the rest. status says whether the portal is active, suspended or pending removal, and creationDateTime, statusChangeDate, lastModified and versionChanged are UTC. region names the data-center region a hosted portal is served from and stays empty on a server installation and when the portal cache is off, while hostedRegion is the region written on the record itself. The settings of the same portal are read with GET api/2.0/settings, its tariff with GET api/2.0/portal/tariff and its quota with GET api/2.0/portal/quota.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The portal record, or an object in which only `tenantId` is filled when the caller has no portal-settings right	TenantWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalPath

StringWrapper getPortalPath(virtualPath)

GET /api/2.0/portal/path

Get a path to the portal

Turns a portal-relative path into the absolute URL a client can open, filling in the scheme, the current portal domain and the virtual root the portal is hosted on. Any signed-in user may call it, nothing has to be called first, and the call is read-only and idempotent - it neither checks that the path exists nor that the caller is allowed to open it. virtualPath is taken as it is: an omitted or empty value yields the portal root, a value starting with / is appended to that root, a value starting with ~/ is resolved against the virtual root, and a value that already starts with http://, https:// or mailto: is handed back unchanged. The answer is a bare JSON string. The domain in the result is the one the portal answers on right now, so a renamed portal starts returning the new domain without any change on the client. Use it to build links that have to survive a rename; the portal's own addresses and settings are read from GET api/2.0/settings instead.

Parameters

Name	In	Type	Description	Notes
virtualPath	query	String	The path to resolve. It is taken as it is: an omitted or empty value yields the portal root, a value starting with `/` is appended to that root, a value starting with `~/` is resolved against the virtual root, and one that already begins with `http://`, `https://` or `mailto:` is handed back unchanged. Nothing checks that the path exists or that the caller may open it.	[optional] [example: `/portal/documents`]

Responses

Status code	Description	Type	Response headers
200	The absolute URL that the given portal-relative path resolves to	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

InvitationLinkWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

sendDeleteInstructions

sendDeleteInstructions()

POST /api/2.0/portal/delete

Send removal instructions

Mails the portal owner the confirmation link that removes this portal; nothing about the portal changes until that link is used. The caller has to be the portal owner and hold the portal-settings right, and on a server installation the last remaining space cannot be removed - the call is refused when every other space has limited access. The letter goes to the owner's own address whoever asked for it, and it warns about the subscription that will stop renewing when the portal is on a paid plan. The operation keeps working while the portal's payment has lapsed, is mutating only in that it sends a message, and is rate-limited to five requests per fifteen minutes per user and path by default, answering 429 above that. Nothing is returned in the body. The link in the letter authorizes DELETE api/2.0/portal/delete, which deletes the portal with all of its rooms, files and accounts and cannot be undone. To pause the portal instead of deleting it, send the deactivation letter with POST api/2.0/portal/suspend.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	OK	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

sendSuspendInstructions

sendSuspendInstructions()

POST /api/2.0/portal/suspend

Send suspension instructions

Mails the portal owner the two confirmation links that deactivate this portal and bring it back again, and records the request in the audit trail; the portal itself is not changed here. The caller has to be the portal owner and hold the portal-settings right, and on a server installation the last remaining space cannot be deactivated - the call is refused when every other space has limited access. The letter always goes to the owner's own address, and the operation keeps working while the portal's payment has lapsed. It is mutating only in that it sends a message, and it is rate-limited to five requests per fifteen minutes per user and path by default, answering 429 above that. Nothing is returned in the body, so a client cannot tell from the answer whether the mail was delivered. The first link in the letter authorizes PUT api/2.0/portal/suspend, which suspends the portal, and the second one authorizes PUT api/2.0/portal/continue, which makes it active again. To remove the portal instead of pausing it, use POST api/2.0/portal/delete.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	OK	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

suspendPortal

suspendPortal()

PUT /api/2.0/portal/suspend

Deactivate a portal

Deactivates this portal: its status becomes suspended and its users can no longer work in it, while all of its rooms, files and accounts stay untouched. It is reached only with the deactivation link that POST api/2.0/portal/suspend mails to the portal owner - that link authorizes the call instead of an authentication token - and the owner is checked again here, so a link issued for another account is refused. On a server installation the last remaining space cannot be deactivated. The call is mutating and idempotent: it sets the status, records the deactivation in the audit trail and refreshes the portal's base domain, and repeating it leaves the portal suspended. Nothing is returned in the body; the new state is read from status in GET api/2.0/portal. Bring the portal back with PUT api/2.0/portal/continue, using the second link from the same letter. To remove the portal and its content for good, use DELETE api/2.0/portal/delete instead - that cannot be undone.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	OK	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

PortalUsersApi

createInvitationLink

InvitationLinkWrapper createInvitationLink(InvitationLinkCreateRequestDto)

POST /api/2.0/portal/users/invitationlink

Create an invitation link

Creates the portal's invitation link for one role and returns it together with the URL to share. A portal keeps at most one link per role, so a call for a role that already has one is refused - read the existing link with GET api/2.0/portal/users/invitationlink/{employeeType} and change it with PUT api/2.0/portal/users/invitationlink instead. Inviting members has to be enabled for the portal (GET api/2.0/settings/invitationsettings), employeeType has to be DocSpaceAdmin, RoomAdmin or User, and expiration, when given, has to lie in the future and is read in the portal time zone. The caller needs the right to add users of that role, only the portal owner may create the DocSpace administrator link, and a link for a paying role additionally needs a free paid seat in the portal quota. The call is mutating and not idempotent. The answer carries the id needed to update or delete the link, the shortened url, maxUseCount and currentUseCount, expiration in the portal time zone - empty for a link that never expires - and isExpired.

Parameters

Name	In	Type	Description	Notes
InvitationLinkCreateRequestDto	body	InvitationLinkCreateRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The invitation link as it was created, with the `id` to address it later and the `url` to share	InvitationLinkWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteInvitationLink

StringWrapper deleteInvitationLink(InvitationLinkDeleteRequestDto)

DELETE /api/2.0/portal/users/invitationlink

Delete an invitation link

Deletes the portal's invitation link with the given id, so the URL shared from it stops letting anyone in; accounts that already joined through it are not touched. Inviting members has to be enabled for the portal (GET api/2.0/settings/invitationsettings) and the link has to exist - a second call with the same id is answered as not found. The caller needs the right to add users of the link's role, and only the portal owner may delete the DocSpace administrator link. The call is destructive and cannot be undone: a link for the same role has to be created again with POST api/2.0/portal/users/invitationlink, and it gets a new id, a new URL and a currentUseCount that starts from zero. Nothing is returned in the body. To stop invitations without losing the links, switch inviting members off for the whole portal with PUT api/2.0/settings/invitationsettings - the links then stay stored but are refused until it is switched on again.

Parameters

Name	In	Type	Description	Notes
InvitationLinkDeleteRequestDto	body	InvitationLinkDeleteRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The invitation link is deleted and its URL no longer lets anyone join the portal	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getInvitationLink

StringWrapper getInvitationLink(employeeType)

GET /api/2.0/portal/users/invite/{employeeType}

Get a legacy invitation link

Deprecated - use POST api/2.0/portal/users/invitationlink and the neighbouring operations under that path, which store the link and let it be read, changed and revoked. Builds a shortened URL that lets whoever opens it join this portal with the role given in the path, and returns it as a bare string; nothing is stored, so the link can afterwards be neither listed nor withdrawn. Inviting members has to be enabled for the portal - GET api/2.0/settings/invitationsettings reports that - otherwise the call is refused. The caller needs the right to add users of the requested role and only the portal owner may ask for a DocSpace administrator link; a caller without that right gets an empty string instead of an error, so treat an empty answer as a refusal. The call changes nothing on the portal and may be repeated, each time returning an equivalent link. The URL carries a confirmation key bound to the calling account and the portal alias; it has no use limit and stops being accepted once the portal's e-mail key lifetime has passed, seven days by default - neither of the two can be set per link, which is what the replacement operations add.

Parameters

Name	In	Type	Description	Notes
employeeType	path	EmployeeType	The role whoever follows the link joins with. Only `DocSpaceAdmin`, `RoomAdmin` and `User` have a link; any other role is refused. The portal keeps at most one link per role, so this value alone identifies it.	[required] [example: `1`] [enum: `All`, `RoomAdmin`, `Guest`, `DocSpaceAdmin`, `User`]

Responses

Status code	Description	Type	Response headers
200	The invitation URL to hand to the invited person, or an empty string when the caller may not invite that role	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

InvitationLinkWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getInvitationLinkByEmployeeType

InvitationLinkWrapper getInvitationLinkByEmployeeType(employeeType)

GET /api/2.0/portal/users/invitationlink/{employeeType}

Get an invitation link by role

Returns the portal's invitation link for one role - the URL to share, how long it lasts and how often it has already been used. Inviting members has to be enabled for the portal (GET api/2.0/settings/invitationsettings) and employeeType has to be DocSpaceAdmin, RoomAdmin or User; the caller needs the right to add users of that role, only the portal owner may read the DocSpace administrator link, and a link for a paying role is shown only while the portal quota still has a free paid seat. The call is read-only and idempotent, but the url it returns is signed for the calling account, so two administrators are handed two different URLs for one and the same link. A role that has no link yet is answered with an empty body and 200 rather than a 404 - create the link with POST api/2.0/portal/users/invitationlink. expiration is in the portal time zone and empty for a link without a deadline, isExpired says whether that deadline has passed, and currentUseCount counts how many accounts have already joined through the link.

Parameters

Name	In	Type	Description	Notes
employeeType	path	EmployeeType	The role whoever follows the link joins with. Only `DocSpaceAdmin`, `RoomAdmin` and `User` have a link; any other role is refused. The portal keeps at most one link per role, so this value alone identifies it.	[required] [example: `1`] [enum: `All`, `RoomAdmin`, `Guest`, `DocSpaceAdmin`, `User`]

Responses

Status code	Description	Type	Response headers
200	The invitation link of that role, or an empty body when the portal has no link for it	InvitationLinkWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalUsersCount

Int64Wrapper getPortalUsersCount()

GET /api/2.0/portal/userscount

Get a number of portal users

Returns how many accounts this portal currently has in the active state, whatever their role, so a client can show the seat usage next to the allowance. Accounts that were invited but have not joined yet and accounts that were disabled or removed are not counted. The caller needs the portal-settings right and is refused without it; the call is read-only and idempotent, and the number moves as soon as an account joins, is disabled or is deleted. The answer is a plain number, not an object. Compare it with countUser and countPaidUser from GET api/2.0/portal/quota to see how much of the allowance is left, and with GET api/2.0/portal/quota/right for the smallest quota that would still hold everyone. When the accounts themselves are needed, and not only how many there are, list them with the People API instead - this operation cannot filter by role, group or status.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The number of accounts of this portal that are in the active state	Int64Wrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Int64Wrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getUserById

UserInfoWrapper getUserById(userID)

GET /api/2.0/portal/users/{userID}

Get a portal user

Returns one user of this portal, addressed by ID, in the shape the portal stores the account: display name, e-mail, contacts, role and status flags, and the dates of the profile. Nothing has to be called first, and the call is read-only and idempotent. Who may be read is decided per pair of accounts: a caller always reads their own profile, a DocSpace administrator reads anyone, a room administrator reads anyone except a guest they have no relation with, and a user or a guest reads nobody but themselves - a pair that is not allowed is refused. An ID that belongs to no account of this portal and an ID of a system account are both answered as not found, so a 404 does not tell the two apart. userID in the path has to be a GUID; the calling user's own profile is easier to fetch with GET api/2.0/people/@self. This operation hands back the internal user record - use GET api/2.0/people/{userid} for the same user in the People format, with the group, quota and access information a client usually needs.

Parameters

Name	In	Type	Description	Notes
userID	path	UUID (uuid)	The portal account the operation acts on, by user ID as `GET api/2.0/people` reports it. An ID belonging to no account of this portal and an ID of an internal system account are both answered as not found.	[required] [example: `00000000-0000-0000-0000-000000000000`]

Responses

Status code	Description	Type	Response headers
200	The account of this portal, in the internal user format	UserInfoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
404	No account with this ID exists on the portal, or the ID belongs to a system account	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

UserInfoWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

markGiftMessageAsRead

markGiftMessageAsRead()

POST /api/2.0/portal/present/mark

Mark a gift message as read

Marks the open-source gift message - the notice a server installation shows about its free edition - as read for the calling user, so the client stops displaying it. Any signed-in user may call it and nothing has to be called first. The flag is stored per user, so marking it read for one account leaves it unread for everybody else on the portal. The call is mutating but idempotent: repeating it changes nothing. It never fails on the caller's behalf - a storage error is written to the portal log and the operation still answers with a success, so the answer is no proof that the flag was saved. Nothing is returned in the body, and no operation reads the flag back or clears it again, which makes the change effectively permanent for that user. It touches only this one notice: portal-wide announcements and the letters the portal sends are unaffected, and other per-user settings are stored through the operations under api/2.0/settings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	OK	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

sendCongratulations

sendCongratulations(Userid, Key)

POST /api/2.0/portal/sendcongratulations

Send congratulations

Sends the welcome letter that follows the registration of a new portal to the account named by userid and switches on the second authentication factor the installation is configured to require after registration; on a hosted portal in custom mode the registration data is mailed to the sales address as well. Open to unauthenticated callers: in place of a token it needs key, the confirmation key of the sign-in link the portal issued for that account, and that key is accepted for one hour after it was created - a wrong, foreign or expired key answers 403 and sends nothing. Both parameters go in the query string. The call is meant to be made once, right after registration; it is not idempotent, and every call within that hour sends the letters again. When the installation asks for SMS or an authenticator app after registration, this call is what enables that method for the whole portal, unless the new account is an internal test address. Nothing is returned in the body and there is no operation that reports afterwards whether the letters were delivered.

Parameters

Name	In	Type	Description	Notes
Userid	query	UUID (uuid)	The account the welcome letter is addressed to, by portal user ID. The key in `key` has to have been issued for this same account, so the pair is what authorises the call.	[required] [example: `00000000-0000-0000-0000-000000000000`]
Key	query	String	The confirmation key from the sign-in link the portal issued for that account, which stands in for a token here. It is accepted for one hour after it was created; a wrong, foreign or expired key answers 403 and sends nothing.	[required] [example: `birthday`]

Responses

Status code	Description	Type	Response headers
200	The welcome letters were sent and the configured second factor was switched on for the portal	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The confirmation key does not match the user or is older than one hour	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

InvitationLinkWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateInvitationLink

InvitationLinkWrapper updateInvitationLink(InvitationLinkUpdateRequestDto)

PUT /api/2.0/portal/users/invitationlink

Update an invitation link

Changes the deadline and the use limit of an existing invitation link, addressed by its id. The role of a link cannot be changed - delete it and create a link for the other role instead. Inviting members has to be enabled for the portal (GET api/2.0/settings/invitationsettings), the link has to exist, and maxUseCount may not be lower than the number of uses the link already has, which GET api/2.0/portal/users/invitationlink/{employeeType} reports as currentUseCount. An expiration in the past is refused; the body is applied as a whole, so omitting expiration clears the deadline and omitting maxUseCount removes the use limit. The caller needs the right to add users of the link's role and only the portal owner may change the DocSpace administrator link. The call is mutating, and repeating it with the same body leaves the link as it is. The whole link comes back as it now stands, with url signed for the calling account - the URL therefore differs between administrators while the link behind it is the same.

Parameters

Name	In	Type	Description	Notes
InvitationLinkUpdateRequestDto	body	InvitationLinkUpdateRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The invitation link as it now stands, with the deadline and the use limit that were applied	InvitationLinkWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SecurityAccessToDevToolsApi

setTenantDevToolsAccessSettings

TenantDevToolsAccessSettingsWrapper setTenantDevToolsAccessSettings(TenantDevToolsAccessSettingsDto)

POST /api/2.0/settings/devtoolsaccess

Set the Developer Tools access settings

Sets whether the portal restricts the User role from using the developer tools (API keys, OAuth apps, webhooks); RoomAdmin and DocSpaceAdmin are never affected by this setting. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). This is a mutating, idempotent, portal-wide call: it applies to every User on the tenant immediately. It returns the saved setting; read the current value at any time from GET api/2.0/settings/devtoolsaccess.

Parameters

Name	In	Type	Description	Notes
TenantDevToolsAccessSettingsDto	body	TenantDevToolsAccessSettingsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved developer tools access restriction for the `User` role	TenantDevToolsAccessSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantDevToolsAccessSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SecurityActiveConnectionsApi

getAllActiveConnections

ActiveConnectionsWrapper getAllActiveConnections()

GET /api/2.0/security/activeconnections

Get active connections

Lists the connections the calling user currently has open on this portal - one item per successful sign-in that is still active - so a client can show where the account is signed in and close what does not belong there. Any signed-in user may call it, nothing has to be called first, and the answer always covers the caller alone: the operation is read-only, idempotent and cannot show another user's connections. Items cover the last year and are ordered newest sign-in first, with the caller's own connection moved to the top and its browser, platform, IP address and location refreshed from the current request. loginEvent is the ID of that own connection and is 0 when the request was authenticated with a token in the Authorization header instead of the portal cookie; nothing is then marked as current, and a user with no stored connections gets a single item describing the current request. country and city are resolved from the IP address and stay empty when it cannot be located. Pass an item's id to PUT api/2.0/security/activeconnections/logout/{loginEventId} to end that one connection.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The caller's active connections, newest sign-in first, with `loginEvent` pointing at the connection the request itself was made with	ActiveConnectionsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ActiveConnectionsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

logOutActiveConnection

BooleanWrapper logOutActiveConnection(loginEventId)

PUT /api/2.0/security/activeconnections/logout/{loginEventId}

Log out one connection

Closes one active connection: the sign-in behind loginEventId is marked inactive, the token and cookie tied to it stop working, the client holding it is disconnected and a logout entry is written to the portal audit trail. Take loginEventId from the id of an item of GET api/2.0/security/activeconnections, which also reports in loginEvent which connection the caller is using, so a client can avoid closing its own. A user may close their own connections, while closing somebody else's requires a DocSpace administrator and any other caller is refused with 403. The call is mutating, destructive for that one session and idempotent, and it leaves every other connection of the user alone - PUT api/2.0/security/activeconnections/logoutallexceptthis is the way to close the rest in one go. Only true means the connection was open and has just been closed; false comes back when this portal has no such active connection, including one that was already closed, and after any other failure.

Parameters

Name	In	Type	Description	Notes
loginEventId	path	Integer (int32)	The sign-in to act on, by login event ID. Take it from the `id` of an item of `GET api/2.0/security/activeconnections`, which also marks the connection the caller is using, so a client can avoid picking its own.	[required] [example: `12345`]

Responses

Status code	Description	Type	Response headers
200	`true` when the connection was open and has been closed, `false` when this portal has no such active connection or the attempt failed	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator and the connection belongs to another user	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

logOutAllActiveConnectionsChangePassword

StringWrapper logOutAllActiveConnectionsChangePassword()

PUT /api/2.0/security/activeconnections/logoutallchangepassword

Log out and reset password

Closes every active connection of the calling user and returns the link that user has to open to set a new password - the answer to a suspicious sign-in seen in GET api/2.0/security/activeconnections. Any signed-in user may call it for their own account and nothing has to be called first; the same clean-up for somebody else is PUT api/2.0/security/activeconnections/logoutall/{userId}. The call is mutating and destructive for sessions - every token and cookie issued to the user before it stops working and the clients holding them are disconnected - and it is not idempotent: the request is written to the portal audit trail, which invalidates the link any earlier call returned, and the caller's own client is handed a fresh cookie in the response and stays signed in through a new connection. The password itself is not changed here, and the link is handed back to the caller rather than mailed to the user: the URL carries a time-limited PasswordChange key, which the confirmation page it opens - or PUT api/2.0/people/{userid}/password - needs to accept the new password. A failure is swallowed instead of reported, so an empty body with status 200 means nothing was done and the call has to be repeated.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The URL the user has to open to set a new password, or an empty result when the operation failed	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

logOutAllActiveConnectionsForUser

logOutAllActiveConnectionsForUser(userId)

PUT /api/2.0/security/activeconnections/logoutall/{userId}

Log out a user everywhere

Closes every active connection of one portal user: the connections are marked inactive, every token and cookie issued to that user before the call stops working, the clients holding them are disconnected and a logout entry is written to the portal audit trail. Nothing has to be called first; userId is the portal user ID that GET api/2.0/people returns. A user may pass their own ID, while ending somebody else's connections requires a DocSpace administrator and any other caller is refused with 403. The call is mutating, destructive for those sessions and idempotent - a user with nothing open is not an error - and it returns no content, so the state afterwards is read from GET api/2.0/security/activeconnections. A caller who ends their own connections is handed a fresh cookie in the response and stays signed in through a new connection. Nothing else about the user changes: the account stays enabled and the password stays valid, and to keep the current connection alive instead use PUT api/2.0/security/activeconnections/logoutallexceptthis.

Parameters

Name	In	Type	Description	Notes
userId	path	UUID (uuid)	The portal account the operation acts on, by user ID as `GET api/2.0/people` reports it. Acting on an account other than the caller's own generally needs administrator rights.	[required] [example: `00000000-0000-0000-0000-000000000000`]

Responses

Status code	Description	Type	Response headers
200	The connections of that user have been closed; the response carries no content	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator and the ID in the path is not their own	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

logOutAllExceptThisConnection

StringWrapper logOutAllExceptThisConnection()

PUT /api/2.0/security/activeconnections/logoutallexceptthis

Log out other connections

Closes every active connection of the calling user except the one this request was made with, so the current client keeps working while every other browser and device is signed out. Any signed-in user may call it for their own account and nothing has to be called first. The connection to keep is the one behind the portal authentication cookie: a request authenticated with a token in the Authorization header has none, and then every connection of the user is closed, including the one that token belongs to - read loginEvent from GET api/2.0/security/activeconnections first to see which connection, if any, will survive. The call is mutating and destructive for the other sessions, and idempotent: the tokens behind them stop working, their clients are disconnected at once and a logout entry is written to the portal audit trail. It answers with the display name of the calling user, while an empty answer with status 200 means the attempt failed and nothing can be assumed about what was closed.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The display name of the calling user, or an empty result when the operation failed	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SecurityAuditTrailDataApi

createAuditTrailReport

DocumentBuilderTaskWrapper createAuditTrailReport(format)

POST /api/2.0/security/audit/events/report

Start audit trail report

Queues a report of the portal's audit trail and returns the state of the background job that builds it. The report covers the period reaching from now back by the audit trail lifetime that GET api/2.0/security/audit/settings/lifetime reports and is never filtered: the query parameters of GET api/2.0/security/audit/events/filter do not apply here. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. The file is not ready when the response arrives - poll GET api/2.0/security/audit/events/report until isCompleted is true, then take resultFileUrl, and treat a non-empty error as a failed build. The finished file is saved to the caller's My documents section, as an XLSX workbook by default or as CSV when format=Csv, in which case resultFileId stays empty and only the name and the URL identify it. One job runs per caller and kind: calling again while the previous one is still building returns that job instead of starting a second, and DELETE api/2.0/security/audit/events/report cancels it.

Parameters

Name	In	Type	Description	Notes
format	query	AuditReportFormat	The format the report file is written in. The workbook format is the default and is the only one that leaves the finished file addressable by ID: a report asked for as CSV comes back with an empty `resultFileId`, so it can only be reached through `resultFileName` and `resultFileUrl`.	[optional] [example: `Xlsx`] [enum: `0`, `1`]

Responses

Status code	Description	Type	Response headers
200	The state of the queued job that builds the audit trail report	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AuditEventArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAuditEventsByFilter

AuditEventArrayWrapper getAuditEventsByFilter(userId, moduleType, actionType, action, entryType, target, from, to, count, startIndex)

GET /api/2.0/security/audit/events/filter

Get filtered audit events

Returns the portal's audit events that match the filters in the query - by the user who acted, the module the action belongs to, the action and its type, the entity type and target, and the period - and is the operation behind the audit trail page. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan; when that option is missing the filters are silently ignored and the answer is the same twenty most recent events that GET api/2.0/security/audit/events/last returns, and when the login history and audit trail section is disabled altogether the call is answered with 402. Take the values accepted by action, actionType, moduleType and entryType from GET api/2.0/security/audit/types, and the tree they belong to from GET api/2.0/security/audit/mappers. A non-default action matches only that action and, combined with target, only its exact value; it also stops moduleType and actionType from narrowing the result, so combine target with entryType instead of action when filtering by target without pinning a single action. from and to are read as UTC instants while date comes back in the portal time zone, count defaults to 100 and cannot exceed it, and the filters are applied before the page window, so a full page means there may be more matching events beyond it. The operation is read-only.

Parameters

Name	In	Type	Description	Notes
userId	query	UUID (uuid)	The user who performed the action, given by portal user ID. Leave it at the empty GUID to keep the events of every user.	[optional] [example: `00000000-0000-0000-0000-000000000001`]
moduleType	query	LocationType	The module the recorded action belongs to, spelled as `GET api/2.0/security/audit/types` lists it under `moduleTypes`. `GET api/2.0/security/audit/mappers` shows which module records which action. The default value keeps every module.	[optional] [example: `Files`] [enum: `0`, `1`, `2`, `3`, `27`, `29`, `30`, `31`]
actionType	query	ActionType	The kind of change the action made, spelled as `GET api/2.0/security/audit/types` lists it under `actionTypes`. The default value keeps every kind.	[optional] [example: `Create`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`]
action	query	MessageAction	The exact action recorded, spelled as the `messageAction` of `GET api/2.0/security/audit/mappers`. Naming one narrows the answer to that single action and overrides `moduleType` and `actionType`, which stop narrowing anything once it is set.	[optional] [example: `FileCreated`] [enum: `1000`, `1001`, `1002`, `1003`, `1004`, `1005`, `1006`, `1007`, `1008`, `1009`, `1010`, `1011`, `1012`, `1013`, `1014`, `1015`, `1016`, `1017`, `1018`, `1019`, `1020`, `1021`, `1022`, `1023`, `1024`, `1025`, `1026`, `1027`, `1028`, `1029`, `4000`, `4001`, `4002`, `4003`, `4004`, `4005`, `4006`, `4007`, `4008`, `4009`, `4010`, `4011`, `4012`, `4013`, `4014`, `4015`, `4016`, `4017`, `4018`, `4019`, `4020`, `4021`, `4022`, `4023`, `4024`, `4025`, `4026`, `4027`, `4028`, `4029`, `4030`, `4031`, `4032`, `4033`, `4034`, `4035`, `4036`, `4037`, `5000`, `5001`, `5002`, `5003`, `5004`, `5005`, `5006`, `5007`, `5008`, `5009`, `5010`, `5011`, `5012`, `5013`, `5014`, `5015`, `5016`, `5017`, `5018`, `5019`, `5020`, `5021`, `5022`, `5023`, `5024`, `5025`, `5026`, `5027`, `5028`, `5029`, `5030`, `5031`, `5032`, `5033`, `5034`, `5035`, `5036`, `5037`, `5038`, `5039`, `5040`, `5041`, `5042`, `5043`, `5044`, `5045`, `5046`, `5047`, `5048`, `5049`, `5050`, `5053`, `5054`, `5055`, `5056`, `5057`, `5058`, `5059`, `5060`, `5061`, `5062`, `5063`, `5064`, `5065`, `5066`, `5068`, `5069`, `5070`, `5071`, `5072`, `5073`, `5074`, `5075`, `5076`, `5077`, `5078`, `5079`, `5080`, `5081`, `5082`, `5083`, `5084`, `5085`, `5086`, `5087`, `5088`, `5089`, `5090`, `5091`, `5092`, `5093`, `5094`, `5095`, `5096`, `5097`, `5098`, `5099`, `5100`, `5101`, `5102`, `5103`, `5104`, `5105`, `5106`, `5107`, `5108`, `5109`, `5110`, `5111`, `5112`, `5113`, `5114`, `5115`, `5116`, `5117`, `5118`, `5119`, `5120`, `5121`, `5122`, `5123`, `5124`, `5125`, `5126`, `5127`, `5128`, `5129`, `5130`, `5131`, `5132`, `5133`, `5150`, `5151`, `5152`, `5153`, `5154`, `5155`, `5156`, `5157`, `5158`, `5159`, `5160`, `5161`, `5162`, `5163`, `5201`, `5202`, `5203`, `5204`, `5205`, `5206`, `5207`, `5501`, `5502`, `5503`, `6000`, `6001`, `6002`, `6003`, `6004`, `6005`, `6006`, `6007`, `6008`, `6009`, `6010`, `6011`, `6012`, `6013`, `6014`, `6015`, `6016`, `6017`, `6018`, `6019`, `6020`, `6021`, `6022`, `6023`, `6024`, `6025`, `6026`, `6027`, `6028`, `6029`, `6030`, `6031`, `6032`, `6033`, `6034`, `6035`, `6036`, `6037`, `6038`, `6039`, `6040`, `6041`, `6042`, `6043`, `6044`, `6045`, `6046`, `6047`, `6048`, `6049`, `6050`, `6051`, `6052`, `6053`, `6054`, `6055`, `6056`, `6057`, `6058`, `6059`, `6060`, `6061`, `6062`, `6063`, `6064`, `6065`, `6066`, `6067`, `6068`, `6069`, `6070`, `6071`, `6072`, `6073`, `6074`, `6075`, `6076`, `6077`, `6078`, `6079`, `6080`, `6081`, `6082`, `6083`, `6084`, `6085`, `6086`, `6087`, `6088`, `6089`, `6090`, `6091`, `6092`, `6093`, `6094`, `6095`, `6096`, `6097`, `6098`, `6099`, `6100`, `6101`, `6102`, `6103`, `6104`, `6105`, `6106`, `6107`, `6108`, `6109`, `7000`, `7001`, `7002`, `7003`, `7004`, `7005`, `9901`, `9902`, `9903`, `9904`, `9905`, `9906`, `9907`, `9908`, `9909`, `-1`]
entryType	query	EntryType	The kind of object the action was performed on, spelled as `GET api/2.0/security/audit/types` lists it under `entryTypes`. Pair it with `target` to filter by object without pinning a single action.	[optional] [example: `File`] [enum: `0`, `1`, `2`, `23`, `24`, `25`, `26`, `27`]
target	query	String	The object the action was performed on, as the audit trail recorded it - a file name, a user account, a room title. It is matched in full and exactly as stored, so it narrows the answer only when `action` or `entryType` is set as well.	[optional] [example: `document.docx`]
from	query	Date (date-time)	The earliest moment an event may have been recorded at, read as a UTC instant. The `date` of the events that come back is in the portal time zone instead, so the two do not line up on a portal that is not on UTC.	[optional] [example: `2024-01-01T00:00:00Z`]
to	query	Date (date-time)	The latest moment an event may have been recorded at, read as a UTC instant in the same way as `from`.	[optional] [example: `2024-01-31T23:59:59Z`]
count	query	Integer (int32)	How many events one page may hold. The maximum is also the default, so a client that wants shorter pages has to ask for them; a full page means there may be further matches beyond it.	[optional] [example: `100`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many matching events to skip before the page begins, counting from the newest. Advance it by `count` to walk backwards through the trail.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	Audit events matching the filters, newest first, or the twenty most recent events when the portal has no audit option	AuditEventArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The login history and audit trail section is not enabled for this portal	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAuditSettings

TenantAuditSettingsResponseWrapper getAuditSettings()

GET /api/2.0/security/audit/settings/lifetime

Get audit lifetime settings

Returns how long this portal keeps its two security logs: loginHistoryLifeTime for login events and auditTrailLifeTime for audit events, both counted in days, together with lastModified, the moment the pair was last saved. The caller needs the portal-settings right of a DocSpace administrator, and in a cloud installation the login history and audit trail section must be enabled for the portal, otherwise the call is answered with 402; the audit option of the pricing plan is not required to read the values. Both numbers lie between 1 and 180 days, and a portal that never changed them reports the default of 180. They define the window the rest of the audit operations work in: GET api/2.0/security/audit/events/last looks exactly this far back, and the reports started by POST api/2.0/security/audit/login/report and POST api/2.0/security/audit/events/report cover exactly this period. The operation is read-only; change the values with POST api/2.0/security/audit/settings/lifetime.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The login history and audit trail lifetimes of the portal, in days	TenantAuditSettingsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The login history and audit trail section is not enabled for this portal	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantAuditSettingsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAuditTrailMappers

AuditTrailProductMapperArrayWrapper getAuditTrailMappers(productType, moduleType)

GET /api/2.0/security/audit/mappers

Get audit trail mappers

Returns the audit vocabulary as the tree it really is: every product, the modules inside it, and for each module the actions it can record together with the type of change and the entity each of them applies to. Pass productType to keep a single product and moduleType to keep a single module inside the products that remain; omit both to get the whole tree. The caller needs the portal-settings right of a DocSpace administrator; the audit option of the pricing plan is not required, and the call is read-only and safe to repeat. Each action carries messageAction, the name to send as the action filter of GET api/2.0/security/audit/events/filter, next to actionType and entity, the values its actionType and entryType filters accept - this is where a caller learns which action belongs to which module instead of guessing. A filter that matches nothing yields an empty list rather than an error. Use GET api/2.0/security/audit/types for the flat lists of the same names.

Parameters

Name	In	Type	Description	Notes
productType	query	ProductType	The product to keep, spelled as `GET api/2.0/security/audit/types` lists it under `productTypes`. Omitting it keeps every product; a value no product matches yields an empty list rather than an error.	[optional] [example: `Documents`] [enum: `2`, `3`, `7`, `8`]
moduleType	query	LocationType	The module to keep inside the products that survive `productType`, spelled as `GET api/2.0/security/audit/types` lists it under `moduleTypes`. Omitting it keeps every module of those products.	[optional] [example: `Files`] [enum: `0`, `1`, `2`, `3`, `27`, `29`, `30`, `31`]

Responses

Status code	Description	Type	Response headers
200	The products with their modules and the actions each module can record	AuditTrailProductMapperArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AuditTrailProductMapperArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAuditTrailReport

DocumentBuilderTaskWrapper getAuditTrailReport()

GET /api/2.0/security/audit/events/report

Get audit trail report status

Returns the state of the audit trail report the calling user has started, and is the operation to poll after POST api/2.0/security/audit/events/report. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. Jobs are kept per user and per report kind: this operation never shows another administrator's report, nor the login history report, which has its own status at GET api/2.0/security/audit/login/report. The answer is empty when no report of this kind is known for the caller; otherwise percentage grows towards 100, isCompleted turns true when the build has ended, error carries the failure message when it ended badly, and resultFileName and resultFileUrl point at the file saved to the caller's My documents section, while resultFileId is filled for an XLSX report only. The operation is read-only and safe to poll every few seconds; a finished job is dropped as soon as the next report of this kind is started.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the caller's audit trail report, or an empty answer when none is known	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AuditTrailTypesWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAuditTrailTypes

AuditTrailTypesWrapper getAuditTrailTypes()

GET /api/2.0/security/audit/types

Get audit trail types

Returns the vocabularies the audit filters are built from: actions lists every action the portal can record, actionTypes the kinds of change they stand for, productTypes the products they belong to, moduleTypes the locations inside those products, and entryTypes the kinds of entity an action can be applied to. The caller needs the portal-settings right of a DocSpace administrator; the audit option of the pricing plan is not required, so the lists can be read on any portal. The operation is read-only, takes no parameters and depends on nothing else. Every value is the name to send in the matching query parameter of GET api/2.0/security/audit/events/filter or GET api/2.0/security/audit/login/filter, so read this operation once and reuse the answer instead of guessing spellings. The response is an untyped object holding those five arrays of names, and it changes only with the portal version. Use GET api/2.0/security/audit/mappers when the relations between products, modules and actions are needed rather than the flat lists.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The action, action type, product, module and entry type names accepted by the audit filters	AuditTrailTypesWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getLastAuditEvents

AuditEventArrayWrapper getLastAuditEvents()

GET /api/2.0/security/audit/events/last

Get recent audit events

Returns the twenty most recent audit events of the portal - the creations, changes, deletions, sharing and settings updates its members made - as the short summary a settings page shows before anyone asks for the full trail. The caller needs the portal-settings right of a DocSpace administrator, and in a cloud installation the login history and audit trail section must be enabled for the portal, otherwise the call is answered with 402. The operation is read-only and takes no parameters: it looks back exactly as far as the audit trail lifetime that GET api/2.0/security/audit/settings/lifetime reports, returns at most twenty events ordered newest first, and cannot be filtered. date is given in the portal time zone, actionText is the readable sentence describing the event with every substituted value shortened to fifty characters here, and target names the entity the action was applied to. An empty list means nothing was recorded inside that period. Use GET api/2.0/security/audit/events/filter to filter by user, module, action or period.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The twenty most recent audit events of the portal, newest first	AuditEventArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The login history and audit trail section is not enabled for this portal	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AuditEventArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

setAuditSettings

TenantAuditSettingsResponseWrapper setAuditSettings(TenantAuditSettingsWrapper)

POST /api/2.0/security/audit/settings/lifetime

Set audit lifetime settings

Sets how long this portal keeps its login history and its audit trail, in days, and returns the pair as it was stored. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. Send both numbers inside settings: each has to be between 1 and 180 days, and a value outside that range is refused with 400 without either number being saved, so read the current pair from GET api/2.0/security/audit/settings/lifetime and resend the one that should stay as it is. The call replaces the stored settings rather than merging them, is idempotent, and takes effect at once: the period covered by GET api/2.0/security/audit/events/last and by both audit reports shrinks or grows with it, and events older than the new lifetime stop being reported. The change is itself recorded in the audit trail.

Parameters

Name	In	Type	Description	Notes
TenantAuditSettingsWrapper	body	TenantAuditSettingsWrapper		[optional]

Responses

Status code	Description	Type	Response headers
200	The login history and audit trail lifetimes as they were stored	TenantAuditSettingsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	A lifetime is outside the allowed range of 1 to 180 days	-	-
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantAuditSettingsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

terminateAuditTrailReport

terminateAuditTrailReport()

DELETE /api/2.0/security/audit/events/report

Terminate audit trail report

Cancels the audit trail report the calling user has running and drops it from the build queue. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. Cancellation is handed to the same background service that builds the report, so a successful answer means the request was accepted rather than that the job has already stopped: poll GET api/2.0/security/audit/events/report to watch it disappear. The operation returns no content and touches only the caller's own audit trail report - the login history report is cancelled by DELETE api/2.0/security/audit/login/report, and no report of another user can be reached from here. It is idempotent: cancelling when nothing is running is not an error. A job stopped before it finished writing leaves nothing in My documents, and a report cancelled by mistake has to be built again with POST api/2.0/security/audit/events/report.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The cancellation of the caller's audit trail report has been accepted	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SecurityBannersVisibilityApi

setTenantBannerSettings

TenantBannerSettingsWrapper setTenantBannerSettings(TenantBannerSettingsDto)

POST /api/2.0/settings/banner

Set the banners visibility

Sets whether the portal's promotional banners are hidden for every user. Available only on an Enterprise license; every other plan is refused regardless of the caller's role. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). The flag only takes effect on a Standalone (self-hosted) installation; on SaaS, banners are always shown no matter what is saved here. This is a mutating, idempotent, portal-wide call: it applies to every user on the tenant immediately. It returns the saved setting; read the current value at any time from GET api/2.0/settings/banner.

Parameters

Name	In	Type	Description	Notes
TenantBannerSettingsDto	body	TenantBannerSettingsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved promotional banners visibility setting	TenantBannerSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantBannerSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SecurityCSPApi

configureCsp

CspWrapper configureCsp(CspRequestsDto)

POST /api/2.0/security/csp

Configure CSP settings

Replaces the list of external domains the portal's Content Security Policy trusts and returns the policy header the portal serves to browsers from that moment on. The list in domains replaces the stored one, so an omitted or empty list falls back to the portal's built-in policy, and every entry that is sent becomes an allowed source for scripts, styles, images, fonts, frames, media and connections at once. An entry may be a host, a host with a scheme, or a wildcard host such as *.example.com; it has to form a valid absolute address and may contain ASCII characters only, and an entry that does not is refused with 400 before anything is saved. The caller needs the portal-settings right of a DocSpace administrator, and the request is also refused with 403 when the header built from the list grows past the size configured for the installation, 15 KB by default. The change applies to the whole portal at once and is idempotent. Read the current state with GET api/2.0/security/csp.

Parameters

Name	In	Type	Description	Notes
CspRequestsDto	body	CspRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The stored domains and the policy header the portal now serves	CspWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	An entry of `domains` is not a valid address or holds non-ASCII characters	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator, or the built policy header exceeds the size allowed for the installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CspWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getCspSettings

CspWrapper getCspSettings()

GET /api/2.0/security/csp

Get CSP settings

Returns the Content Security Policy this portal serves: domains, the external hosts an administrator has allowed, and header, the whole policy value built from them together with the portal's own defaults and the integrations it has switched on. The operation is anonymous and reachable cross-origin - no token is needed - because the login and editor front-ends read it before anyone has signed in. It is read-only for the caller, but it does repair the portal's cached policy when the cache has lost it, so a call can rebuild the header instead of only reading it. The answer honours If-Modified-Since: send back the Last-Modified value of an earlier answer and an unchanged policy comes back as an empty not-modified response rather than a body. domains is an empty list on a portal nobody has configured, while header is filled from the defaults even then. Change the allowed domains with POST api/2.0/security/csp, which does need a DocSpace administrator.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The allowed domains and the full policy header the portal serves	CspWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CspWrapper

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

SecurityFirebaseApi

docRegisterPusnNotificationDevice

FireBaseUserWrapper docRegisterPusnNotificationDevice(FirebaseRequestsDto)

POST /api/2.0/settings/push/docregisterdevice

Registers one mobile device of the calling user for the push notifications of the Documents application, by storing the Firebase token that device was issued together with the initial isSubscribed state. The token is handed out by Firebase to the mobile client, so obtain it there before calling: nothing here checks it, and it is kept as an opaque string of up to 255 characters. Every signed-in member registers its own devices, whatever its role - owner, administrator, user or guest - and a registration is bound to the caller and the current portal, so another member's devices cannot be touched. The call is safe to repeat, but it is not an update: a token already registered comes back as it stands and isSubscribed from the request is ignored, so switch an existing registration on or off with PUT api/2.0/settings/push/docsubscribe instead. What comes back is the stored registration, with application always doc and isSubscribed as stored. Only a subscribed device is sent the room activity messages, such as an invitation to a room, a role change, an archived room or a new document in a room, and only while the installation itself is configured with Firebase credentials.

Parameters

Name	In	Type	Description	Notes
FirebaseRequestsDto	body	FirebaseRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The stored device registration of the calling user, with the Firebase token, the `doc` application and the subscription state as they are kept	FireBaseUserWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

FireBaseUserWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

subscribeDocumentsPushNotification

FireBaseUserWrapper subscribeDocumentsPushNotification(FirebaseRequestsDto)

PUT /api/2.0/settings/push/docsubscribe

Set push subscription

Switches the push notifications of the Documents application on or off for one already registered device of the calling user: send that device's Firebase token together with isSubscribed true to let the messages through or false to stop them. The device has to be registered first with POST api/2.0/settings/push/docregisterdevice, and only the subscription state is written - the token is matched, never changed. Every signed-in member manages its own devices, whatever its role - owner, administrator, user or guest - and a token that belongs to another member or to another portal is not matched at all, so nothing of theirs can be switched. Repeating the call with the same pair leaves the registration as it is. What comes back is the updated registration, while an empty response means no registration of the caller carries that token and nothing was stored - register the device and call again. A device switched off keeps its token stored but is left out of the delivery, and the other devices of the same member are unaffected. Which kinds of notification the account receives at all is a separate setting, read with GET api/2.0/settings/notification/{type}.

Parameters

Name	In	Type	Description	Notes
FirebaseRequestsDto	body	FirebaseRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The device registration as it stands after the change, or an empty response when no registration of the calling user carries the token that was sent	FireBaseUserWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

FireBaseUserWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SecurityLoginHistoryApi

createLoginHistoryReport

DocumentBuilderTaskWrapper createLoginHistoryReport(format)

POST /api/2.0/security/audit/login/report

Start login history report

Queues a report of the portal's login history and returns the state of the background job that builds it. The report covers the period reaching from now back by the login history lifetime that GET api/2.0/security/audit/settings/lifetime reports and is never filtered: the query parameters of GET api/2.0/security/audit/login/filter do not apply here. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. The file is not ready when the response arrives - poll GET api/2.0/security/audit/login/report until isCompleted is true, then take resultFileUrl, and treat a non-empty error as a failed build. The finished file is saved to the caller's My documents section, as an XLSX workbook by default or as CSV when format=Csv, in which case resultFileId stays empty and only the name and the URL identify it. One job runs per caller and kind: calling again while the previous one is still building returns that job instead of starting a second, and DELETE api/2.0/security/audit/login/report cancels it.

Parameters

Name	In	Type	Description	Notes
format	query	AuditReportFormat	The format the report file is written in. The workbook format is the default and is the only one that leaves the finished file addressable by ID: a report asked for as CSV comes back with an empty `resultFileId`, so it can only be reached through `resultFileName` and `resultFileUrl`.	[optional] [example: `Xlsx`] [enum: `0`, `1`]

Responses

Status code	Description	Type	Response headers
200	The state of the queued job that builds the login history report	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

LoginEventArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getLastLoginEvents

LoginEventArrayWrapper getLastLoginEvents()

GET /api/2.0/security/audit/login/last

Get recent login events

Returns the twenty most recent login events of the whole portal - successful sign-ins, sign-outs and failed attempts alike - as the short summary a settings page shows before anyone asks for the full history. The caller needs the portal-settings right of a DocSpace administrator, and in a cloud installation the login history and audit trail section must be enabled for the portal, otherwise the call is answered with 402. The operation is read-only and takes no parameters: the number of events is fixed at twenty, nothing can be filtered, and events are ordered newest first. date is given in the portal time zone, actionText is the readable sentence describing the event with every substituted value shortened to fifty characters here, and country and city are resolved from the IP address and stay empty when it cannot be located. An empty list means the portal has recorded no login events yet. Use GET api/2.0/security/audit/login/filter to filter by user, action or period and to page through the whole history.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The twenty most recent login events of the portal, newest first	LoginEventArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The login history and audit trail section is not enabled for this portal	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getLoginEventsByFilter

LoginEventArrayWrapper getLoginEventsByFilter(userId, action, from, to, count, startIndex)

GET /api/2.0/security/audit/login/filter

Get filtered login events

Returns the portal's login events that match the filters in the query - by user, by login action and by period - and is the operation behind the login history page. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan; when that option is missing the filters are silently ignored and the answer is the same twenty most recent events that GET api/2.0/security/audit/login/last returns, and when the login history and audit trail section is disabled altogether the call is answered with 402. Omit a filter to match everything. from and to are read as UTC instants while date comes back in the portal time zone, count defaults to 100 and cannot exceed it, startIndex skips events from the newest end, and the page window is applied to the log before the filters, so a page can hold fewer items than count while older matches still exist. The operation is read-only; take the values accepted by action from GET api/2.0/security/audit/types.

Parameters

Name	In	Type	Description	Notes
userId	query	UUID (uuid)	The user whose sign-in attempts are kept, given by portal user ID. Leave it at the empty GUID to keep the events of every user.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
action	query	MessageAction	The sign-in action recorded, spelled as `GET api/2.0/security/audit/types` lists it under `actions` - a successful login, a failed one, a logout. The default value keeps every action.	[optional] [example: `FileCreated`] [enum: `1000`, `1001`, `1002`, `1003`, `1004`, `1005`, `1006`, `1007`, `1008`, `1009`, `1010`, `1011`, `1012`, `1013`, `1014`, `1015`, `1016`, `1017`, `1018`, `1019`, `1020`, `1021`, `1022`, `1023`, `1024`, `1025`, `1026`, `1027`, `1028`, `1029`, `4000`, `4001`, `4002`, `4003`, `4004`, `4005`, `4006`, `4007`, `4008`, `4009`, `4010`, `4011`, `4012`, `4013`, `4014`, `4015`, `4016`, `4017`, `4018`, `4019`, `4020`, `4021`, `4022`, `4023`, `4024`, `4025`, `4026`, `4027`, `4028`, `4029`, `4030`, `4031`, `4032`, `4033`, `4034`, `4035`, `4036`, `4037`, `5000`, `5001`, `5002`, `5003`, `5004`, `5005`, `5006`, `5007`, `5008`, `5009`, `5010`, `5011`, `5012`, `5013`, `5014`, `5015`, `5016`, `5017`, `5018`, `5019`, `5020`, `5021`, `5022`, `5023`, `5024`, `5025`, `5026`, `5027`, `5028`, `5029`, `5030`, `5031`, `5032`, `5033`, `5034`, `5035`, `5036`, `5037`, `5038`, `5039`, `5040`, `5041`, `5042`, `5043`, `5044`, `5045`, `5046`, `5047`, `5048`, `5049`, `5050`, `5053`, `5054`, `5055`, `5056`, `5057`, `5058`, `5059`, `5060`, `5061`, `5062`, `5063`, `5064`, `5065`, `5066`, `5068`, `5069`, `5070`, `5071`, `5072`, `5073`, `5074`, `5075`, `5076`, `5077`, `5078`, `5079`, `5080`, `5081`, `5082`, `5083`, `5084`, `5085`, `5086`, `5087`, `5088`, `5089`, `5090`, `5091`, `5092`, `5093`, `5094`, `5095`, `5096`, `5097`, `5098`, `5099`, `5100`, `5101`, `5102`, `5103`, `5104`, `5105`, `5106`, `5107`, `5108`, `5109`, `5110`, `5111`, `5112`, `5113`, `5114`, `5115`, `5116`, `5117`, `5118`, `5119`, `5120`, `5121`, `5122`, `5123`, `5124`, `5125`, `5126`, `5127`, `5128`, `5129`, `5130`, `5131`, `5132`, `5133`, `5150`, `5151`, `5152`, `5153`, `5154`, `5155`, `5156`, `5157`, `5158`, `5159`, `5160`, `5161`, `5162`, `5163`, `5201`, `5202`, `5203`, `5204`, `5205`, `5206`, `5207`, `5501`, `5502`, `5503`, `6000`, `6001`, `6002`, `6003`, `6004`, `6005`, `6006`, `6007`, `6008`, `6009`, `6010`, `6011`, `6012`, `6013`, `6014`, `6015`, `6016`, `6017`, `6018`, `6019`, `6020`, `6021`, `6022`, `6023`, `6024`, `6025`, `6026`, `6027`, `6028`, `6029`, `6030`, `6031`, `6032`, `6033`, `6034`, `6035`, `6036`, `6037`, `6038`, `6039`, `6040`, `6041`, `6042`, `6043`, `6044`, `6045`, `6046`, `6047`, `6048`, `6049`, `6050`, `6051`, `6052`, `6053`, `6054`, `6055`, `6056`, `6057`, `6058`, `6059`, `6060`, `6061`, `6062`, `6063`, `6064`, `6065`, `6066`, `6067`, `6068`, `6069`, `6070`, `6071`, `6072`, `6073`, `6074`, `6075`, `6076`, `6077`, `6078`, `6079`, `6080`, `6081`, `6082`, `6083`, `6084`, `6085`, `6086`, `6087`, `6088`, `6089`, `6090`, `6091`, `6092`, `6093`, `6094`, `6095`, `6096`, `6097`, `6098`, `6099`, `6100`, `6101`, `6102`, `6103`, `6104`, `6105`, `6106`, `6107`, `6108`, `6109`, `7000`, `7001`, `7002`, `7003`, `7004`, `7005`, `9901`, `9902`, `9903`, `9904`, `9905`, `9906`, `9907`, `9908`, `9909`, `-1`]
from	query	Date (date-time)	The earliest moment an event may have been recorded at, read as a UTC instant. The `date` of the events that come back is in the portal time zone instead, so the two do not line up on a portal that is not on UTC.	[optional] [example: `2024-01-15T10:30:00Z`]
to	query	Date (date-time)	The latest moment an event may have been recorded at, read as a UTC instant in the same way as `from`.	[optional] [example: `2024-01-15T10:30:00Z`]
count	query	Integer (int32)	How many events one page may hold. The maximum is also the default, so a client that wants shorter pages has to ask for them.	[optional] [example: `1`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many events to skip before the page begins, counting from the newest. It is applied to the log before the filters, so a page can hold fewer events than `count` while older matches still exist.	[optional] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	Login events matching the filters, newest first, or the twenty most recent events when the portal has no audit option	LoginEventArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The login history and audit trail section is not enabled for this portal	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

LoginEventArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getLoginHistoryReport

DocumentBuilderTaskWrapper getLoginHistoryReport()

GET /api/2.0/security/audit/login/report

Get login history report status

Returns the state of the login history report the calling user has started, and is the operation to poll after POST api/2.0/security/audit/login/report. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. Jobs are kept per user and per report kind: this operation never shows another administrator's report, nor the audit trail report, which has its own status at GET api/2.0/security/audit/events/report. The answer is empty when no report of this kind is known for the caller; otherwise percentage grows towards 100, isCompleted turns true when the build has ended, error carries the failure message when it ended badly, and resultFileName and resultFileUrl point at the file saved to the caller's My documents section, while resultFileId is filled for an XLSX report only. The operation is read-only and safe to poll every few seconds; a finished job is dropped as soon as the next report of this kind is started.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the caller's login history report, or an empty answer when none is known	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

terminateLoginHistoryReport

terminateLoginHistoryReport()

DELETE /api/2.0/security/audit/login/report

Terminate login history report

Cancels the login history report the calling user has running and drops it from the build queue. The caller needs the portal-settings right of a DocSpace administrator plus the audit option of the portal's pricing plan, otherwise the call is answered with 402. Cancellation is handed to the same background service that builds the report, so a successful answer means the request was accepted rather than that the job has already stopped: poll GET api/2.0/security/audit/login/report to watch it disappear. The operation returns no content and touches only the caller's own login history report - the audit trail report is cancelled by DELETE api/2.0/security/audit/events/report, and no report of another user can be reached from here. It is idempotent: cancelling when nothing is running is not an error. A job stopped before it finished writing leaves nothing in My documents, and a report cancelled by mistake has to be built again with POST api/2.0/security/audit/login/report.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The cancellation of the caller's login history report has been accepted	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan has no audit option, or the login history and audit trail section is not enabled	-	-
403	The caller does not have the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SecurityOAuth2Api

generateJwtToken

StringWrapper generateJwtToken()

GET /api/2.0/security/oauth2/token

Generate JWT token

Issues a short-lived JWT that identifies the calling user to the identity service, the component that stores the OAuth2 applications of this installation and their consents. Any signed-in user may call it, nothing has to be prepared first, and the token always describes the caller - it cannot be issued on behalf of somebody else. The token is signed with the installation's own key and carries the user ID, name and e-mail, the portal ID and address, whether the caller is an administrator or a guest, and whether the portal's developer tools setting leaves OAuth2 applications open to ordinary users. It expires five minutes after it was issued and is meant to be presented to the identity service in the x-signature header, not to this API: requests to the portal are authorized with the token that POST api/2.0/authentication returns, and this JWT is not accepted in its place. The call is read-only and gives the token back as a plain string; ask for a fresh one per exchange instead of storing it.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The signed JWT identifying the caller, valid for five minutes	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SmtpOperationStatusRequestsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SecuritySMTPSettingsApi

getSmtpOperationStatus

SmtpOperationStatusRequestsWrapper getSmtpOperationStatus()

GET /api/2.0/smtpsettings/smtp/test/status

Get SMTP test status

Returns the state of the test message that GET api/2.0/smtpsettings/smtp/test queued for this portal, and is the operation to poll while that test runs. A test has to be queued first; the caller needs the portal-settings right of a DocSpace administrator, and the SMTP settings section has to be enabled for the portal, otherwise the call is answered with 402. The call changes no settings, but it is not free of consequence: the first answer that reports completed true also discards the finished job, so a later call no longer knows about it - take error from that answer and keep it. An empty answer means the portal has no test on record, either because none was queued or because its result has already been read. While the job runs, percents climbs to 100 and status names the step reached, such as Connect to host or Send test message; error is empty until something fails and stays empty when the relay accepted the message. id identifies the queued job, of which a portal only ever has one.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the test message of the portal, or an empty answer when no test is on record	SmtpOperationStatusRequestsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The SMTP settings section is not enabled for this portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSmtpSettings

SmtpSettingsWrapper getSmtpSettings()

GET /api/2.0/smtpsettings/smtp

Get SMTP settings

Returns the SMTP relay this portal sends its own mail through - host, port, sender identity and authentication flags - as it is stored for the portal. Nothing has to be called first; the caller needs the portal-settings right of a DocSpace administrator, and the SMTP settings section has to be enabled for the portal, otherwise the call is answered with 402. The call is read-only and safe to repeat. isDefaultSettings is true when the portal has no settings of its own and runs on the mail configuration of the installation: a standalone installation then shows those server-wide values, while a cloud portal is answered with an empty settings object instead, so an empty host together with isDefaultSettings true means nothing was ever saved here. credentialsUserPassword always comes back empty - the stored password cannot be read back, and a client that saves the settings again has to ask the user for it once more. port is the port that was saved, and settings saved without one are stored with 25. To find out whether the returned relay actually accepts mail, queue a test with GET api/2.0/smtpsettings/smtp/test.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The SMTP settings stored for the portal, with an empty password and `isDefaultSettings` telling whether the configuration of the installation is in use	SmtpSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The SMTP settings section is not enabled for this portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SmtpSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

resetSmtpSettings

SmtpSettingsWrapper resetSmtpSettings()

DELETE /api/2.0/smtpsettings/smtp

Reset SMTP settings

Deletes the SMTP settings of this portal and puts it back on the mail configuration of the installation, so the portal stops using the relay saved by POST api/2.0/smtpsettings/smtp. Nothing has to be called first; the caller needs the portal-settings right of a DocSpace administrator, and the SMTP settings section has to be enabled for the portal, otherwise the call is answered with 402. The call is destructive and cannot be undone - the host, the sender identity and the credentials are gone and have to be entered again - but it is idempotent, and on a portal that has no settings of its own it changes nothing. Portal mail itself keeps working as long as the installation has a relay of its own configured. The answer holds the settings that are in force after the reset, always with isDefaultSettings true: the server-wide values in a standalone installation, an empty settings object in a cloud portal, and an empty credentialsUserPassword in both. Read them back at any time with GET api/2.0/smtpsettings/smtp.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The settings in force after the reset - the configuration of the installation, or an empty settings object in a cloud portal	SmtpSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The SMTP settings section is not enabled for this portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SmtpSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveSmtpSettings

SmtpSettingsWrapper saveSmtpSettings(SmtpSettingsDto)

POST /api/2.0/smtpsettings/smtp

Save SMTP settings

Stores the SMTP relay that this portal will hand all of its own mail to, replacing whatever was saved before and taking the portal off the mail configuration of the installation. Nothing has to be called first; the caller needs the portal-settings right of a DocSpace administrator, and the SMTP settings section has to be enabled for the portal, otherwise the call is answered with 402. The call is mutating and idempotent - the same body saved twice leaves the same settings - and it applies to the next message the portal sends. The settings are stored unverified, no connection to host is attempted, so queue GET api/2.0/smtpsettings/smtp/test afterwards to find out whether they work. host and senderAddress must not be empty, senderDisplayName has to be present, and enableAuth true also requires credentialsUserName and credentialsUserPassword; a request that misses any of them is rejected and nothing is saved. port falls back to 25 when it is omitted, and useNtlm is accepted but not stored, so the saved settings always authenticate with a plain user name and password. The answer repeats the stored settings with the password emptied. Use DELETE api/2.0/smtpsettings/smtp to return to the configuration of the installation.

Parameters

Name	In	Type	Description	Notes
SmtpSettingsDto	body	SmtpSettingsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The SMTP settings now stored for the portal, with an empty password	SmtpSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The SMTP settings section is not enabled for this portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SmtpSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

testSmtpSettings

SmtpOperationStatusRequestsWrapper testSmtpSettings()

GET /api/2.0/smtpsettings/smtp/test

Test SMTP settings

Queues a background job that sends a test message through the SMTP settings currently stored for the portal to the email address of the calling user, and returns the state of that job. Save the settings with POST api/2.0/smtpsettings/smtp first: the job always takes the stored settings and nothing can be passed to it here. The caller needs the portal-settings right of a DocSpace administrator, and the SMTP settings section has to be enabled for the portal, otherwise the call is answered with 402. The call is mutating, it sends mail, and it is rate-limited to five requests per fifteen minutes per user and path by default, answering 429 above that; while a test is still running the same job is returned instead of a second one being started. The message has not been sent when the answer arrives: poll GET api/2.0/smtpsettings/smtp/test/status until completed is true, then read error - empty means the relay accepted the message, otherwise it carries the reason. percents climbs to 100 and status names the step reached, such as Connect to host or Send test message. An unreachable relay is reported in error after a 30-second connection timeout, not as a failed request.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the queued test message, to be polled until `completed` is true	SmtpOperationStatusRequestsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The SMTP settings section is not enabled for this portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SmtpOperationStatusRequestsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SettingsAccessToDevToolsApi

getTenantAccessDevToolsSettings

TenantDevToolsAccessSettingsWrapper getTenantAccessDevToolsSettings()

GET /api/2.0/settings/devtoolsaccess

Get the Developer Tools access settings

Returns whether the portal currently restricts the User role from using the developer tools (API keys, OAuth apps, webhooks). Requires an authenticated session; every role can read the restriction, even though it only limits what a User may do, not what a RoomAdmin or DocSpaceAdmin may do. This is a read-only, idempotent call. Change the restriction with POST api/2.0/security/devtoolsaccess, which requires the EditPortalSettings permission.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Whether the `User` role is currently restricted from using the developer tools	TenantDevToolsAccessSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantDevToolsAccessSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SettingsAuthorizationApi

getAuthServices

AuthServiceRequestsArrayWrapper getAuthServices()

GET /api/2.0/settings/authservice

Get the authorization services

Returns the catalogue of third-party storage and authorization providers DocSpace can integrate with (for example Amazon S3, Dropbox, Google, or Telegram), including whichever keys were last saved for each one that currently has any configured. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). This is a read-only, idempotent call, and the list is not paginated; entries are ordered by the provider's configured display order. Only providers that expose at least one manageable key are included, so a provider with nothing to configure is omitted entirely. Save or change a provider's keys with POST api/2.0/settings/authservice.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Third-party providers with a manageable key, and their last-saved key values	AuthServiceRequestsArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AuthServiceRequestsArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveAuthKeys

BooleanWrapper saveAuthKeys(AuthServiceRequestsDto)

POST /api/2.0/settings/authservice

Save the authorization keys

Saves the authorization keys for one third-party storage or authorization provider, identified by name, or clears them when every submitted key is left empty. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission); a provider that does not allow its keys to be changed from the API rejects the call outright. A provider that is only available on a paid plan additionally requires the portal's tariff to include third-party storage, or Standalone licensing, before the call is accepted. Keys that fail the provider's own validation are cleared and the call is rejected rather than left partially applied. This is a mutating, idempotent call: resaving identical keys succeeds and reports no change. It returns whether the keys actually changed, not the keys themselves; connecting Telegram or an external database through this call also triggers the matching real-time connection update.

Parameters

Name	In	Type	Description	Notes
AuthServiceRequestsDto	body	AuthServiceRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Whether the provider's keys actually changed	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The submitted keys failed the provider's own validation	-	-
402	The provider is a paid option not covered by the portal's current pricing plan	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ConnectionTestResultWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

testExternalDatabaseConnection

ConnectionTestResultWrapper testExternalDatabaseConnection(ExternalDatabaseSettings)

POST /api/2.0/settings/authservice/externaldb/test

Test external database connection

Probes connectivity to an external database using the settings supplied in the request, without saving them or affecting the portal's own configuration. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). SQLite is only accepted as a target on a Standalone (self-hosted) installation; requesting it on SaaS is reported as a failed connection rather than an error. This is a read-only call, safe to retry. A failed connection is not an HTTP error: the response always comes back as a normal success with success=false and an error message describing what went wrong.

Parameters

Name	In	Type	Description	Notes
ExternalDatabaseSettings	body	ExternalDatabaseSettings		[optional]

Responses

Status code	Description	Type	Response headers
200	Connection test result: a success flag and, on failure, an error message	ConnectionTestResultWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsBannersVisibilityApi

getTenantBannerSettings

TenantBannerSettingsWrapper getTenantBannerSettings()

GET /api/2.0/settings/banner

Get the banners visibility

Returns whether the portal's promotional banners are currently hidden from every user's interface. Requires an authenticated session; every role can read it, since the flag affects what they see regardless of their own permissions. This is a read-only, idempotent call. The flag only takes effect on a Standalone (self-hosted) installation; on SaaS, banners are always shown no matter what is saved here. Change the setting with POST api/2.0/settings/banner, which additionally requires an Enterprise license.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Whether the portal's promotional banners are currently hidden	TenantBannerSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantBannerSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SettingsCommonSettingsApi

closeAdminHelper

closeAdminHelper()

PUT /api/2.0/settings/closeadminhelper

Close the admin helper

Dismisses the administrator helper tip for the caller, so it is not shown again on this account. Available only to a DocSpace administrator, which includes the portal Owner, on a Standalone (self-hosted) installation running outside white-label custom mode; every other caller is refused. This is a mutating, idempotent call scoped to the calling account only; it never affects other administrators. It returns no data on success.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The admin helper tip was dismissed for the caller	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
405	The caller is not a DocSpace administrator, or the portal is on SaaS, custom mode, or not Standalone	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

completeWizard

WizardSettingsWrapper completeWizard(WizardRequestsDto)

PUT /api/2.0/settings/wizard/complete

Complete the Wizard settings

Finishes the initial portal setup wizard: sets the owner's password and locale, applies the supplied license if one is required, and marks the wizard as completed so it is not shown again. This call is not for a normal logged-in session: it requires a confirmation link bearing the Wizard claim, of the kind issued when a new portal is created, and the link is consumed as part of authenticating the request; the caller must also hold the EditPortalSettings permission. An empty password or a malformed email address is rejected without completing the wizard, and so is a missing, invalid, or expired license, or a license whose user quota does not cover the portal. This call is meant to run once per portal; running it again is accepted but has no further effect once the wizard is already completed. It returns the resulting wizard settings, including the completed flag.

Parameters

Name	In	Type	Description	Notes
WizardRequestsDto	body	WizardRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Resulting wizard settings, including the completed flag	WizardSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The email address is malformed, or the password is empty	-	-
402	The supplied license is missing, invalid, expired, or its user quota does not cover the portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WizardSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

configureDeepLink

TenantDeepLinkSettingsWrapper configureDeepLink(DeepLinkConfigurationRequestsDto)

POST /api/2.0/settings/deeplink

Configure the deep link settings

Sets how the portal responds when a client opens a DocSpace link on a mobile device: always in the browser, always in the native app, or asking the user to choose each time. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). The handling mode must be one of the documented enum values; anything else is rejected without being saved. This is a mutating, idempotent call: sending the same mode again leaves the setting unchanged. It returns the saved deep link settings, including the timestamp of the last change; read the current value at any time, including anonymously, from GET api/2.0/settings/deeplink.

Parameters

Name	In	Type	Description	Notes
DeepLinkConfigurationRequestsDto	body	DeepLinkConfigurationRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved deep link handling settings	TenantDeepLinkSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The handling mode is not one of the supported deep link handling values	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantDeepLinkSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deletePortalColorTheme

CustomColorThemesSettingsWrapper deletePortalColorTheme(id)

DELETE /api/2.0/settings/colortheme

Delete a color theme

Removes a custom color theme from the portal by its ID. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). An ID belonging to one of the built-in default themes is not removable; the call succeeds but leaves the theme list unchanged. If the deleted theme was the currently selected one, the theme with the lowest remaining ID is selected automatically. This is a mutating, idempotent call: deleting an ID that is already gone succeeds without error and again leaves nothing changed. It returns the full updated theme configuration, including the (possibly new) selected theme.

Parameters

Name	In	Type	Description	Notes
id	query	Integer (int32)	The theme to remove, by theme ID. An ID belonging to a built-in theme leaves the list untouched, and so does one that is already gone - neither is reported as an error. Removing the theme currently in use moves the portal to the remaining theme with the lowest ID.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	Updated color theme configuration: saved themes, selected theme, and plan limit	CustomColorThemesSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CustomColorThemesSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getDeepLinkSettings

TenantDeepLinkSettingsWrapper getDeepLinkSettings()

GET /api/2.0/settings/deeplink

Get the deep link settings

Returns how the portal currently responds when a client opens a DocSpace link on a mobile device: always in the browser, always in the native app, or asking the user to choose. No permission is required; anonymous callers can read it too. This is a read-only, idempotent call. The response supports conditional requests: send the standard If-Modified-Since header with the previous lastModified value, and an unchanged response comes back empty instead of resending the settings. Change the mode with POST api/2.0/settings/deeplink, which requires the EditPortalSettings permission.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Current deep link handling settings	TenantDeepLinkSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantDeepLinkSettingsWrapper

Authorization

PaymentSettingsWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPaymentSettings

PaymentSettingsWrapper getPaymentSettings()

GET /api/2.0/settings/payment

Get the payment settings

Returns the portal's payment-related configuration: the sales contact email, the URL to buy or extend a subscription, whether the portal is Standalone, the current license's trial status and expiration date, and the maximum quota quantity that can be purchased at once. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). This is a read-only, idempotent call. It remains reachable even while the portal's own subscription payment is overdue, since this is how the caller finds the link to resolve it.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Payment-related settings: sales contact, buy URL, Standalone flag, license, and quota cap	PaymentSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalColorTheme

CustomColorThemesSettingsWrapper getPortalColorTheme()

GET /api/2.0/settings/colortheme

Get a color theme

Returns the portal's color theme configuration: every saved custom theme, which one is currently selected, and how many custom themes the plan still allows. No permission is required; anonymous callers can read it too. This is a read-only, idempotent call. The response supports conditional requests: send the standard If-Modified-Since header with the previous lastModified value, and an unchanged response comes back empty instead of resending the same settings. A limit of 0 means the plan does not cap the number of custom themes.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Current color theme configuration: saved themes, selected theme, and plan limit	CustomColorThemesSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CustomColorThemesSettingsWrapper

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalHostname

StringWrapper getPortalHostname()

GET /api/2.0/settings/machine

Get the portal hostname

Returns the hostname the current request arrived on, exactly as sent in the HTTP Host header, so a client mid-setup can learn the address the portal is actually reachable at. This call is not for a normal logged-in session: it requires a confirmation link bearing the Wizard claim, of the kind generated during initial portal setup, and the link is consumed as part of authenticating the request. This is a read-only, idempotent call. The value reflects whatever the caller connected through, including a reverse proxy's public name, and is not necessarily the tenant's configured alias or mapped domain.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Hostname the current request arrived on	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalLogo

StringWrapper getPortalLogo()

GET /api/2.0/settings/logo

Get a portal logo

Returns the absolute URL of the portal's current logo image, already resolved against the active white-label branding. Requires an authenticated session; every role, including Guest, can read it. This is a read-only, idempotent call. The response supports conditional requests: send the standard If-Modified-Since header with the previous lastModified value, and an unchanged response comes back empty instead of resending the same URL. The URL points at whatever image is currently configured, including the default DocSpace logo when no custom branding has been set.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Absolute URL of the portal's current logo image	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPortalSettings

SettingsWrapper getPortalSettings(withpassword)

GET /api/2.0/settings

Get the portal settings

Returns the current portal's general configuration: branding, culture, feature flags, and DocSpace/Standalone mode, everything the client needs to render its shell before or after login. No permission is required, but the response shape depends on the caller's identity. An anonymous caller receives only the public subset (culture, branding, DocSpace/Standalone flags, deep link data, setup-wizard and join-by-domain hints); once authenticated, the response also includes tenant-specific fields such as the owner ID, time zone, invitation limit, AI/banner/dev-tools flags, and, for a DocSpace administrator, the tenant wallet's low-balance flag. This is a read-only, idempotent call. Pass withPassword=true to also receive the parameters (salt, iteration count, hash size) used to hash the password client-side before it is sent to the authentication endpoints; these are only added for an anonymous caller or when explicitly requested, never as part of the default authenticated response.

Parameters

Name	In	Type	Description	Notes
withpassword	query	Boolean	Whether the answer also carries the salt, iteration count and hash size a client needs to hash a password before sending it to the authentication operations. They are included for an anonymous caller anyway; for a signed-in one they are left out unless this is set.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	Current portal settings, tailored to the caller's authentication state	SettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SettingsWrapper

Authorization

SocketSettingsWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSocketSettings

SocketSettingsWrapper getSocketSettings()

GET /api/2.0/settings/socket

Get the socket settings

Returns the base URL of the portal's real-time notification hub (Socket.IO), which the client connects to for live updates such as file changes, presence, or quota alerts. Requires an authenticated session; every role can read it. This is a read-only, idempotent call. The value comes from server-side configuration and cannot be changed through this API; an empty url means the portal has no notification hub configured and the client should not attempt to connect.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Base URL of the portal's real-time notification hub	SocketSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSupportedCultures

STRINGArrayWrapper getSupportedCultures()

GET /api/2.0/settings/cultures

Get supported languages

Returns the two- or four-letter language codes of every culture currently enabled on the portal (for example en-US), used to populate a language picker before or after login. No permission is required; anonymous callers can read it too. This is a read-only, idempotent call, and the list is not paginated. The response supports conditional requests: an unchanged result is signaled instead of resending the same list. The set of enabled cultures is a portal-wide configuration value, not a per-user preference.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Language codes of every culture currently enabled on the portal	STRINGArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

STRINGArrayWrapper

Authorization

TenantAiAccessSettingsWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantAiAccessSettings

TenantAiAccessSettingsWrapper getTenantAiAccessSettings()

GET /api/2.0/settings/ai-access

Get the AI access settings

Returns whether AI functionality (chat, agents, vectorization) is currently available on the portal at all; AI is enabled by default. Requires an authenticated session; every role can read it. This is a read-only, idempotent call. When the setting is disabled, every AI-specific endpoint and folder is unavailable regardless of the caller's own permissions; this call only reports the portal-wide switch, not any per-user entitlement.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Whether AI functionality is currently enabled for the portal	TenantAiAccessSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantUserInvitationSettings

TenantUserInvitationSettingsWrapper getTenantUserInvitationSettings()

GET /api/2.0/settings/invitationsettings

Get the user invitation settings

Returns whether the portal currently allows inviting new members and new guests at all. No permission is required; anonymous callers can read it too, since the invitation flow itself may run before the caller has signed in. This is a read-only, idempotent call. The response supports conditional requests: send the standard If-Modified-Since header with the previous lastModified value, and an unchanged response comes back empty instead of resending the same settings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Whether inviting new members and new guests is currently allowed	TenantUserInvitationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantUserInvitationSettingsWrapper

Authorization

TimezonesRequestsArrayWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTimeZones

TimezonesRequestsArrayWrapper getTimeZones()

GET /api/2.0/settings/timezones

Get time zones

Returns every time zone known to the host machine, each with its IANA identifier and a human-readable display name, ordered from the most negative to the most positive UTC offset. This call is not for a normal logged-in session: it requires a confirmation link bearing the Wizard or Administrators claim, of the kind generated during initial portal setup or issued by an administrator, and the link is consumed as part of authenticating the request. This is a read-only, idempotent call, and the list is not paginated. Use the returned id values wherever the portal expects a time zone identifier; an unrecognized value is rejected there, not here.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Every time zone known to the host, with its IANA ID and display name	TimezonesRequestsArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveDefaultFolder

StudioDefaultPageSettingsWrapper saveDefaultFolder(DefaultProductRequestDto)

PUT /api/2.0/settings/defaultfolder

Set the default folder

Sets which folder the current user's account opens into by default, such as My Documents, the rooms list, or favorites. Requires an authenticated session; every role may set its own default, and the change never affects any other user. Only folder types the client actually offers as a landing page are accepted; picking My Documents (USER) as a Guest is rejected too, since guests have no personal storage. This is a mutating, idempotent call. It returns the saved setting.

Parameters

Name	In	Type	Description	Notes
DefaultProductRequestDto	body	DefaultProductRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved default folder setting for the current user	StudioDefaultPageSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

StudioDefaultPageSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveDnsSettings

StringWrapper saveDnsSettings(DnsSettingsRequestsDto)

PUT /api/2.0/settings/dns

Save the DNS settings

Maps a custom domain name onto the current tenant, or clears the mapping, so the portal becomes reachable under the caller's own DNS name instead of only its default alias. Available only on a Standalone (self-hosted) installation; on SaaS the call is always refused. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). Disable the mapping by passing enable=false, in which case the domain name in the request is ignored. A domain that collides with the portal's reserved base domain, or otherwise fails validation, is rejected without changing the current mapping. This is a mutating, idempotent call. On success the previous domain also stops answering, and any CSP configuration referencing it is updated to the new one.

Parameters

Name	In	Type	Description	Notes
DnsSettingsRequestsDto	body	DnsSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Confirmation that the DNS mapping was updated	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The domain name is invalid, or collides with the portal's reserved base domain	-	-
402	This option is not available under the portal's current pricing plan	-	-
405	The portal is not a Standalone installation, so a custom domain cannot be mapped	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveMailDomainSettings

StringWrapper saveMailDomainSettings(MailDomainSettingsRequestsDto)

POST /api/2.0/settings/maildomainsettings

Save the mail domain settings

Overwrites the portal's trusted mail domain configuration, which controls which email domains are treated as already verified when a user is invited or self-registers. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). When the requested mode is a custom domain list, every domain is normalized to lowercase and checked against the expected hostname format; a domain that fails the check, or an empty custom list, causes the whole call to be rejected without saving anything. For the other modes the domain list in the request is ignored. The inviteUsersAsVisitors flag controls whether users who join through a trusted domain are added as full members or as visitors, and takes effect on the next join rather than retroactively. This is a mutating, idempotent call: repeating it with the same body leaves the portal in the same state. On success it returns a confirmation message, not the saved settings themselves; read them back from GET api/2.0/settings.

Parameters

Name	In	Type	Description	Notes
MailDomainSettingsRequestsDto	body	MailDomainSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Confirmation message that the trusted mail domain settings were saved	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CustomColorThemesSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

savePortalColorTheme

CustomColorThemesSettingsWrapper savePortalColorTheme(CustomColorThemesSettingsRequestsDto)

PUT /api/2.0/settings/colortheme

Save a color theme

Adds or updates a custom color theme, or changes which theme is selected, for the whole portal. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). Pass theme to create or edit one: an existing theme is matched and updated by its ID, a new one is appended, and an ID that collides with a built-in default theme is treated as a request to create a new custom theme instead of overwriting the default. Once the plan's custom-theme limit is reached, a new theme is silently not added rather than rejected with an error, so check the returned themes count against limit before assuming it was saved. Pass selected to switch the active theme; an ID that does not match any existing theme is ignored. This is a mutating call, not strictly idempotent once the limit has been reached. It returns the full updated theme configuration.

Parameters

Name	In	Type	Description	Notes
CustomColorThemesSettingsRequestsDto	body	CustomColorThemesSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Updated color theme configuration: saved themes, selected theme, and plan limit	CustomColorThemesSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setTenantAiAccessSettings

TenantAiAccessSettingsWrapper setTenantAiAccessSettings(TenantAiAccessSettingsDto)

POST /api/2.0/settings/ai-access

Set the AI access settings

Turns AI functionality (chat, agents, vectorization) on or off for the whole portal; AI is enabled by default. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission); every other caller is refused. Disabling it immediately hides the AI Agents folder from root folder listings, makes AI status checks report disabled, and makes AI chat endpoints unreachable for every user on the tenant, not only the caller. This is a mutating, idempotent, portal-wide call, and the change is pushed to already-connected clients over the real-time notification hub rather than waiting for their next request. It returns the saved setting.

Parameters

Name	In	Type	Description	Notes
TenantAiAccessSettingsDto	body	TenantAiAccessSettingsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved AI access setting for the portal	TenantAiAccessSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, so the AI access setting cannot be changed	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantAiAccessSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateEmailActivationSettings

EmailActivationSettingsWrapper updateEmailActivationSettings(EmailActivationSettings)

PUT /api/2.0/settings/emailactivation

Update the email activation settings

Updates the current user's own preference for whether the email confirmation prompt is displayed on their account. Requires an authenticated session; every role may change its own setting, and the change never affects any other user. This is a mutating, idempotent call. It returns the settings exactly as submitted, without validating them against the account's actual email confirmation state, so show can be set to true even after the address is already confirmed.

Parameters

Name	In	Type	Description	Notes
EmailActivationSettings	body	EmailActivationSettings		[optional]

Responses

Status code	Description	Type	Response headers
200	Email activation settings exactly as submitted	EmailActivationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

EmailActivationSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateInvitationSettings

TenantUserInvitationSettingsWrapper updateInvitationSettings(TenantUserInvitationSettingsRequestDto)

PUT /api/2.0/settings/invitationsettings

Update the user invitation settings

Sets whether the portal allows inviting new members and new guests. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). Disabling member or guest invitations only blocks creating new invitations going forward; it does not revoke links already issued or remove members already invited. This is a mutating, idempotent, portal-wide call. It returns the saved setting; read the current value at any time, including anonymously, from GET api/2.0/settings/invitationsettings.

Parameters

Name	In	Type	Description	Notes
TenantUserInvitationSettingsRequestDto	body	TenantUserInvitationSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved user invitation settings	TenantUserInvitationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantUserInvitationSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsCookiesApi

getCookieSettings

CookieSettingsWrapper getCookieSettings()

GET /api/2.0/settings/cookiesettings

Get the cookie lifetime settings

Returns how long an authentication session of this portal stays valid: lifeTime in minutes together with the enabled flag that says whether that limit is applied at all. The caller needs the portal-settings right of a DocSpace administrator - the portal owner and a DocSpace administrator qualify, any other member is refused - and the call is read-only. The pair describes the whole portal rather than the calling user, and it is never empty: a portal nobody has configured answers lifeTime 1440, one day, with enabled false. Read the two fields together, because the number alone does not say how long a session lasts - while enabled is false the stored number is ignored and an issued session is honoured for a year, and lifeTime 0 with enabled true means a session that never expires on its own. On an installation whose configuration hides the cookie section the built-in default pair comes back instead of the stored one. GET api/2.0/settings carries the same flag as cookieSettingsEnabled without the number; change the pair with PUT api/2.0/settings/cookiesettings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The authentication session lifetime of the portal in minutes together with the flag that says whether that limit is applied	CookieSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CookieSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateCookieSettings

StringWrapper updateCookieSettings(CookieSettingsRequestsDto)

PUT /api/2.0/settings/cookiesettings

Update the cookie lifetime settings

Stores how long an authentication session of this portal stays valid: lifeTime in minutes together with the enabled flag that switches the limit on. The caller needs the portal-settings right of a DocSpace administrator - the portal owner and a DocSpace administrator qualify, any other member is refused - and on an installation whose configuration hides the cookie section nothing is stored and the call is answered with 402. A lifeTime above 9999 minutes is not rejected but clamped to 9999, while 0 or less clears the number instead, which with enabled true leaves sessions that never expire on their own. Any positive lifeTime raises the session version of the portal: every session issued before the call stops being accepted, and with enabled true the connections behind them are dropped as well. The caller is signed in again inside the same call and gets a fresh session cookie in the response, so a client that keeps sending the token it held before this call is the one locked out. The change is recorded in the audit trail. What comes back is a localized confirmation message; read the stored pair with GET api/2.0/settings/cookiesettings.

Parameters

Name	In	Type	Description	Notes
CookieSettingsRequestsDto	body	CookieSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	A localized message confirming that the session lifetime has been saved	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The installation hides the cookie lifetime section, or the portal's payment has lapsed	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

PaymentCalculationWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsDocsCloudApi

calculateDevPack

PaymentCalculationWrapper calculateDevPack(DocsCloudDevPackRequestDto)

POST /api/2.0/settings/docscloud/calculatedevpack

Calculate the Docs Connect Dev Pack switch cost

Prices the upgrade of the paid Docs Connect subscription of the current portal to Docs Connect Dev Pack for the requested number of users, without changing the subscription or charging anything. It applies the same preconditions as the switch itself: the portal must hold an active Docs Connect subscription, must not already hold a Docs Connect Dev Pack one, and its tariff must not be delayed or unpaid; the quotas and the state of the current tariff are listed by GET api/2.0/portal/tariff. The caller must be a DocSpace administrator of a portal registered with the billing service. The call is read-only and idempotent, so it can be repeated for different quantities before any switch is made. It returns the amount that switching would cost, the three-letter ISO 4217 currency of that amount, the quantity the amount was calculated for, and the identifier of the billing operation; an empty result means the billing service could not price the switch, which should then not be attempted. The switch itself is performed by POST api/2.0/settings/docscloud/switchtodevpack with the same quantity and takes no identifier from this response; to price a change in the number of users of a subscription the portal already has, use PUT api/2.0/portal/payment/calculatewallet instead.

Parameters

Name	In	Type	Description	Notes
DocsCloudDevPackRequestDto	body	DocsCloudDevPackRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The cost of switching to Docs Connect Dev Pack for the requested quantity, or an empty result if the billing service could not price it	PaymentCalculationWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The quantity is below the allowed minimum, the portal has no active Docs Connect subscription, or it already has a Docs Connect Dev Pack subscription	-	-
402	The portal tariff is delayed or not paid, so the switch cannot be priced	-	-
403	The caller is not a DocSpace administrator, or the billing service is not configured	-	-
404	The portal is not registered as a billing customer, or the Docs Connect and Docs Connect Dev Pack wallet products are not configured on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createTenantQuotaReport

DocumentBuilderTaskWrapper createTenantQuotaReport()

POST /api/2.0/settings/docscloud/tenant/quota/report

Start the Docs Connect quota report

Queues a background job that renders the current Docs Connect user quota of the portal into an xlsx file and saves that file in the My documents folder of the calling user; the report lists the editor and the viewer users with the type and the expiration date of each, and summarizes the internal, external and remaining users against the license limits. The file is not ready when the response arrives: poll GET api/2.0/settings/docscloud/tenant/quota/report until isCompleted is true, then take the file from resultFileId or resultFileUrl, and use DELETE api/2.0/settings/docscloud/tenant/quota/report to cancel a job that is still running. The caller must be a portal administrator allowed to edit the portal settings. The portal should have an activated Docs Connect tenant: this call does not check that, and without a tenant the job itself fails and reports the reason in the error of the status response. One report per caller runs at a time: while a report of this user is still being built, the call describes that running job and no second generation is started, so a repeated call is safe. What comes back is the initial state of the job, with percentage 0 and a created status, not the report; the report is a point-in-time snapshot and carries the generation date in its file name. To read the same data as JSON, without building a file, use GET api/2.0/settings/docscloud/tenant/quota.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The initial state of the queued report generation job, with zero progress and an uncompleted status	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DocsCloudTenantWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenant

DocsCloudTenantWrapper getTenant(refresh)

GET /api/2.0/settings/docscloud/tenant

Get the Docs Connect tenant

Returns the Docs Connect tenant of the current portal: the Docs Connect server assigned to the portal, with its address, the date the tenant subscription ends and the payment the tenant was created for. A tenant exists only after a Docs Connect subscription has been granted, by POST api/2.0/settings/docscloud/trial or by a Docs Connect purchase, and only on an installation where the Docs Connect service is configured. The caller must be a portal administrator allowed to edit the portal settings. The call is read-only and idempotent, and it is served from a cache that keeps the tenant for an hour and the absence of a tenant for a minute, so pass refresh=true right after a subscription change to read the current state from Docs Connect instead. In the result, address is the absolute URL of the assigned server, isActive tells whether endDate is still in the future, and the dates are in UTC. An empty result means the portal has no Docs Connect tenant yet, which is the normal state before a subscription and not an error, so this is the operation to call to find out whether Docs Connect is activated at all. The license and server details, the editing settings, the user quota and the usage statistics are not part of it: they live in GET api/2.0/settings/docscloud/tenant/info, .../tenant/config, .../tenant/quota and .../tenant/usage, each of which fails with 400 while the portal has no activated tenant.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Pass `true` to skip the cached copy and request the tenant from Docs Connect again, replacing the cached one; with the default `false` the answer may be up to an hour old, or up to a minute old while the portal has no tenant.	[optional] [default to `false`]

Responses

Status code	Description	Type	Response headers
200	The Docs Connect tenant of the portal, or an empty result if no Docs Connect tenant is assigned to it	DocsCloudTenantWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantConfig

DocsCloudConfigWrapper getTenantConfig(refresh)

GET /api/2.0/settings/docscloud/tenant/config

Get the Docs Connect tenant configuration

Returns the configuration of the Docs Connect tenant of the current portal: its name, the security secret and header name, the file size limit and anonymous access switch of the server, the WOPI switch and the IP filter rules. The portal must have an activated Docs Connect tenant, granted by POST api/2.0/settings/docscloud/trial or by a Docs Connect purchase: an empty result from GET api/2.0/settings/docscloud/tenant means there is none and this call fails with 400. The caller must be a portal administrator allowed to edit the portal settings, on an installation where the Docs Connect service is configured. The call is read-only, idempotent and cached for an hour, so pass refresh=true to read the current state from Docs Connect; the same values are changed by PUT api/2.0/settings/docscloud/tenant/config, which drops the cached copy itself, so no refresh is needed after an update. In the result, security.secret is a credential, so the response should be treated as sensitive; server.fileSizeLimit is in bytes and an update cannot raise it above 209715200 (200 MB); and an empty or absent ipFilter.rules means no address restriction is configured. The license and server version, the address of the assigned server, the per-user quota and the usage counters are not part of it: they live in .../tenant/info, .../tenant, .../tenant/quota and .../tenant/usage.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Pass `true` to skip the cached copy and request the configuration from Docs Connect again, replacing the cached one; with the default `false` the answer may be up to an hour old.	[optional] [default to `false`]

Responses

Status code	Description	Type	Response headers
200	The configuration of the Docs Connect tenant of the portal, with its security, server, WOPI and IP filter settings	DocsCloudConfigWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal has no activated Docs Connect tenant, so there is no configuration to return	-	-
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DocsCloudConfigWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantInfo

DocsCloudTenantInfoWrapper getTenantInfo(refresh)

GET /api/2.0/settings/docscloud/tenant/info

Get the Docs Connect tenant information

Returns the Docs Connect license of the current portal, the Docs Connect server serving it, the user limits of that license and the editor and viewer usage counted against them for the current period. The portal must have an activated Docs Connect tenant, granted by POST api/2.0/settings/docscloud/trial or by a Docs Connect purchase: an empty result from GET api/2.0/settings/docscloud/tenant means there is none and this call fails with 400. The caller must be a portal administrator allowed to edit the portal settings, on an installation where the Docs Connect service is configured. The call is read-only, idempotent and cached for a minute, so pass refresh=true right after a subscription change to read the current state from Docs Connect. In the result, license.valid is when the license expires and license.trial is reported as false once the portal holds a paid Docs Connect or Docs Connect Dev Pack subscription, even when the license itself still says trial; usersLimit caps the editors and the viewers allowed, stats counts the active, internal, external and remaining users of each of those two kinds over the last stats.periodDay days, and the dates are in UTC. The editing settings, the per-user quota lists and the address of the assigned server live in .../tenant/config, .../tenant/quota and .../tenant, while .../tenant/usage gives one active-user total instead of this per-role breakdown.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Pass `true` to skip the cached copy and request the license, server and usage information from Docs Connect again, replacing the cached one; with the default `false` the answer may be up to a minute old.	[optional] [default to `false`]

Responses

Status code	Description	Type	Response headers
200	The Docs Connect license and server information of the portal, with the user limits of the license and the usage statistics for the current period	DocsCloudTenantInfoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal has no activated Docs Connect tenant, so there is no license information to return	-	-
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DocsCloudTenantInfoWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantQuota

DocsCloudQuotaWrapper getTenantQuota(refresh)

GET /api/2.0/settings/docscloud/tenant/quota

Get the Docs Connect tenant quota

Returns the Docs Connect user quota of the current portal: the users who currently count as Docs Connect editors and the users who count as viewers, each with the identifier Docs Connect knows them by and the date their quota entry expires. The portal must have an activated Docs Connect tenant, granted by POST api/2.0/settings/docscloud/trial or by a Docs Connect purchase: an empty result from GET api/2.0/settings/docscloud/tenant means there is none and this call fails with 400. The caller must be a portal administrator allowed to edit the portal settings, on an installation where the Docs Connect service is configured. The call is read-only, idempotent and cached for a minute, so pass refresh=true to read the current state from Docs Connect. In the result, users holds the editor entries and usersView the viewer entries, both unordered; userId is the DocSpace user ID for a portal member and an identifier of Docs Connect's own for anyone else; expire is the date and time the entry expires, as a UTC string; and empty lists mean no user has been counted yet. It lists the users themselves, not the counters: the license limits with the per-role totals are in GET api/2.0/settings/docscloud/tenant/info, a single active-user total is in .../tenant/usage, and the same lists as a downloadable xlsx file are produced by POST api/2.0/settings/docscloud/tenant/quota/report.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Pass `true` to skip the cached copy and request the user quota from Docs Connect again, replacing the cached one; with the default `false` the answer may be up to a minute old.	[optional] [default to `false`]

Responses

Status code	Description	Type	Response headers
200	The editor and viewer users of the Docs Connect tenant of the portal, with the expiration date of each entry	DocsCloudQuotaWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal has no activated Docs Connect tenant, so there is no user quota to return	-	-
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DocsCloudQuotaWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantQuotaReport

DocumentBuilderTaskWrapper getTenantQuotaReport()

GET /api/2.0/settings/docscloud/tenant/quota/report

Get the Docs Connect quota report status

Returns the state of the Docs Connect user quota report that the current user started with POST api/2.0/settings/docscloud/tenant/quota/report, so that the caller can follow the generation and pick up the resulting file. It reports the caller's own job only: a report started by another administrator is not visible here, and an empty result means this user has no job, because none was started, because it was terminated, or because a finished one has already been cleared (a job state is kept for a day, and starting a new report drops the previous finished one); that is a normal state and not an error. The caller must be a portal administrator allowed to edit the portal settings. The call is read-only and idempotent, and it is meant to be polled while the job runs. In the result, percentage goes from 0 to 100 and isCompleted becomes true both on success and on failure, so check error: it is empty when the report was built and carries the failure message otherwise; resultFileId, resultFileName and resultFileUrl are filled in only once the file exists, and that file also stays in the My documents folder of the caller. Use the POST operation on this path to start a report and the DELETE one to cancel it.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the Docs Connect quota report job of the caller, or an empty result if there is no such job	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DocsCloudUsageWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTenantUsage

DocsCloudUsageWrapper getTenantUsage(refresh)

GET /api/2.0/settings/docscloud/tenant/usage

Get the Docs Connect tenant usage

Returns the Docs Connect usage of the current portal: the number of users who have been active in Docs Connect in the current period, and the moment that period is counted from. The portal must have an activated Docs Connect tenant, granted by POST api/2.0/settings/docscloud/trial or by a Docs Connect purchase: an empty result from GET api/2.0/settings/docscloud/tenant means there is none and this call fails with 400. The caller must be a portal administrator allowed to edit the portal settings, on an installation where the Docs Connect service is configured. The call is read-only, idempotent and cached for a minute, so pass refresh=true to read the current state from Docs Connect. In the result, activeCount counts the users seen since since, which is in UTC, and it is one total for the whole tenant, with no split by role and no limit to compare it against. For the editor and viewer breakdown with the license limits use GET api/2.0/settings/docscloud/tenant/info, and for the users counted one by one GET api/2.0/settings/docscloud/tenant/quota.

Parameters

Name	In	Type	Description	Notes
refresh	query	Boolean	Pass `true` to skip the cached copy and request the usage statistics from Docs Connect again, replacing the cached one; with the default `false` the answer may be up to a minute old.	[optional] [default to `false`]

Responses

Status code	Description	Type	Response headers
200	The number of active Docs Connect users of the portal and the date the count starts from	DocsCloudUsageWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal has no activated Docs Connect tenant, so there is no usage information to return	-	-
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

startDocsCloudTrial

BooleanWrapper startDocsCloudTrial()

POST /api/2.0/settings/docscloud/trial

Start the Docs Connect trial

Activates the free Docs Connect trial subscription for the current portal, and, once a Docs Connect server is assigned to the portal, allows the address of that server in the Content Security Policy settings. The portal tariff must be in the trial or paid state (not delayed and not unpaid), and the portal must not already hold a Docs Connect trial, Docs Connect or Docs Connect Dev Pack subscription: the quotas of the current tariff are listed by GET api/2.0/portal/tariff. The caller must be a portal administrator allowed to edit the portal settings, on an installation where the billing service is configured. The operation changes the portal subscription and is not idempotent: repeating it after a successful activation fails with 400. It returns true when the trial has been granted, and false when the billing service declines it (for example, when this portal has already used its trial), in which case nothing is changed. It never buys a paid plan: an existing paid Docs Connect subscription is moved to Docs Connect Dev Pack by POST api/2.0/settings/docscloud/switchtodevpack instead.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Boolean value: true if the trial subscription is activated, false if the billing service declines it	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal already has a Docs Connect trial, Docs Connect or Docs Connect Dev Pack subscription	-	-
402	The portal tariff is delayed or not paid, so the trial cannot be started	-	-
403	The caller is not allowed to edit the portal settings, or the billing service is not configured	-	-
404	The Docs Connect trial quota is not available on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

switchToDevPack

BooleanWrapper switchToDevPack(DocsCloudDevPackRequestDto)

POST /api/2.0/settings/docscloud/switchtodevpack

Switch Docs Connect to Docs Connect Dev Pack

Upgrades the paid Docs Connect subscription of the current portal to Docs Connect Dev Pack for the requested number of users, charging the price difference to the portal wallet and moving the Docs Connect license to the new product. The portal must hold an active Docs Connect subscription, must not already hold a Docs Connect Dev Pack one, and its tariff must not be delayed or unpaid: the quotas and the state of the current tariff are listed by GET api/2.0/portal/tariff, and the amount that will be charged is returned by POST api/2.0/settings/docscloud/calculatedevpack for the same quantity. The caller must be a DocSpace administrator of a portal registered with the billing service. The switch is synchronous, mutating and not idempotent: repeating it after a successful call fails with 400, and concurrent calls for one portal are serialized so that the wallet is charged only once. It returns true when the subscription has been switched, and false when the billing service declines or fails to perform the switch, in which case nothing is charged and the portal stays on Docs Connect. Only the Docs Connect to Docs Connect Dev Pack direction is supported: to change the number of users of a subscription the portal already has, or to schedule a reversion from Docs Connect Dev Pack back to Docs Connect at the next billing period, use PUT api/2.0/portal/payment/updatewallet instead.

Parameters

Name	In	Type	Description	Notes
DocsCloudDevPackRequestDto	body	DocsCloudDevPackRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Boolean value: true if the subscription is switched to Docs Connect Dev Pack, false if the billing service declines it	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The quantity is below the allowed minimum, the portal has no active Docs Connect subscription, or it already has a Docs Connect Dev Pack subscription	-	-
402	The portal tariff is delayed or not paid, so the subscription cannot be switched	-	-
403	The caller is not a DocSpace administrator, or the billing service is not configured	-	-
404	The portal is not registered as a billing customer, or the Docs Connect and Docs Connect Dev Pack wallet products are not configured on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DocsCloudConfigWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

terminateTenantQuotaReport

terminateTenantQuotaReport()

DELETE /api/2.0/settings/docscloud/tenant/quota/report

Terminate the Docs Connect quota report

Cancels the Docs Connect user quota report that the current user started with POST api/2.0/settings/docscloud/tenant/quota/report and removes its job, so that a new report can be started right away. There is no precondition: the call is accepted even when this user has no report job at all, and it affects the caller's own job only, never one started by another administrator. The caller must be a portal administrator allowed to edit the portal settings. The cancellation is asynchronous and idempotent: 200 means the request has been queued for the report worker, not that the job has already stopped, so poll GET api/2.0/settings/docscloud/tenant/quota/report until it returns an empty result. Nothing is returned in the body. A report file that has already been saved in the My documents folder of the caller is left there and has to be deleted through the file operations if it is no longer wanted.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The termination request has been queued for the report worker; the response has no body	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateTenantConfig

DocsCloudConfigWrapper updateTenantConfig(DocsCloudConfig)

PUT /api/2.0/settings/docscloud/tenant/config

Update the Docs Connect tenant configuration

Replaces the configuration of the Docs Connect tenant of the current portal: its name, the security secret and header name, the file size limit and anonymous access switch of the server, the WOPI switch and the IP filter rules; it returns the configuration as Docs Connect stored it. The portal must have an activated Docs Connect tenant, granted by POST api/2.0/settings/docscloud/trial or by a Docs Connect purchase: an empty result from GET api/2.0/settings/docscloud/tenant means there is none and this call fails with 400. Read the current values with GET api/2.0/settings/docscloud/tenant/config first and send back whole sections: the sections left out of the request are not sent to Docs Connect at all, while a section that is present is sent with all of its fields, so a field left unset inside it goes out as 0, false or empty. The caller must be a portal administrator allowed to edit the portal settings, on an installation where the Docs Connect service is configured. The call is mutating, synchronous and idempotent, it is recorded in the portal audit trail, and it drops the cached configuration itself, so the next read returns the new values without refresh=true. The tenantName, security.secret, security.header and every ipFilter.rules address are capped at 255 characters and server.fileSizeLimit at 209715200 bytes (200 MB); a value outside those bounds is rejected with 400 before anything reaches Docs Connect. It changes these settings only, never the subscription, the user quota or the license.

Parameters

Name	In	Type	Description	Notes
DocsCloudConfig	body	DocsCloudConfig		[optional]

Responses

Status code	Description	Type	Response headers
200	The configuration of the Docs Connect tenant as Docs Connect stored it after the update	DocsCloudConfigWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	A text field is longer than 255 characters, the file size limit is outside 0-209715200 bytes, or the portal has no activated Docs Connect tenant	-	-
403	The caller is not allowed to edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsEncryptionApi

getStorageEncryptionProgress

DoubleNullableWrapper getStorageEncryptionProgress()

GET /api/2.0/settings/encryption/progress

Get the storage encryption progress

Returns how far the running encryption or decryption of the installation storage has got, as a percentage from 0 to 100. It reports the run started by POST api/2.0/settings/encryption/start, whose direction, encryption or decryption, is told by GET api/2.0/settings/encryption/settings. An empty response means no run is in flight and no recent result is remembered: the value of a finished run is kept for one minute after it completes and then dropped, so poll often enough not to miss the end of the operation. A value of -1 means the build does not offer storage encryption at all, and on an installation that is not a server one the call is refused rather than answered. Unlike the other encryption operations, this one asks for no portal-settings permission: any authenticated member of the portal may read the progress, which is intentional, because the portals are unavailable while the run is on and their users need to see when it ends. Nothing is written and the call is safe to repeat.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Encryption or decryption progress as a percentage, or empty when no run is in flight	DoubleNullableWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
405	Storage encryption is not available on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DoubleNullableWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getStorageEncryptionSettings

EncryptionSettingsWrapper getStorageEncryptionSettings()

GET /api/2.0/settings/encryption/settings

Get the storage encryption settings

Returns the encryption state of the installation storage: the status, which is one of decrypted, encryption started, encrypted or decryption started, and the flag saying whether users are mailed when an encryption run begins. The password is deliberately blanked out, so the field always comes back empty even on an encrypted installation. The caller is expected to have the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, on a server installation with an unrestricted access space; on any other installation, and whenever the check fails, the operation answers with an empty body instead of an error. An empty answer is therefore not proof that encryption is off, only that the settings cannot be read in this context. Nothing is written and the call is safe to repeat. Use GET api/2.0/settings/encryption/progress to follow a run that is in flight, and POST api/2.0/settings/encryption/start to encrypt or decrypt the storage.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The encryption status and the notify-users flag, with the password blanked out; empty where encryption settings cannot be read	EncryptionSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit portal settings	-	-
405	Storage encryption is not available on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

EncryptionSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

startStorageEncryption

BooleanWrapper startStorageEncryption(StorageEncryptionRequestsDto)

POST /api/2.0/settings/encryption/start

Start the storage encryption

Queues encryption of everything the installation keeps in its local storage, or decryption of it when the data is already encrypted: the saved encryption state decides the direction, so the same call encrypts a decrypted installation and decrypts an encrypted one. It covers the whole server, not one portal, and only a server installation with the feature switched on can run it, with neither the portal storage nor the CDN pointing at a third-party provider: reset those first with DELETE api/2.0/settings/storage and DELETE api/2.0/settings/storage/cdn. No backup may be running, and the backup schedules of all portals are dropped as part of starting. The caller needs the permission to edit portal settings, that is the portal owner or a DocSpace admin, and an unrestricted access space. This is a long, disruptive operation: every portal is put into the encryption state and stays unavailable until it ends, so do not repeat the call while it runs, and follow it with GET api/2.0/settings/encryption/progress instead. The password is generated on the server and never returned by the API. Pass notifyUsers=true to mail every user before the portals go down. The response is true once the job is queued, and false where encryption is switched off, nothing being started then.

Parameters

Name	In	Type	Description	Notes
StorageEncryptionRequestsDto	body	StorageEncryptionRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	True when the encryption job has been queued; false in a build where storage encryption is switched off	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal pricing plan does not include storage encryption	-	-
403	The caller may not edit portal settings, or this installation does not allow storage encryption	-	-
405	Storage encryption is not available on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsGreetingSettingsApi

getGreetingSettings

StringWrapper getGreetingSettings()

GET /api/2.0/settings/greetingsettings

Get greeting settings

Returns the greeting title of the current portal - the caption shown as the welcome heading on the sign-in page, kept as the portal name. Any authenticated user may call it and no administrative right is needed; the call is read-only. The title comes back as a bare string and is never empty: when the portal has no title of its own, the built-in default caption is returned instead, localized to the caller's language. Because of that fallback this operation cannot tell a saved title from the default one - call GET api/2.0/settings/greetingsettings/isdefault when that distinction matters. The same string is part of the portal settings answer as the greetingSettings field of GET api/2.0/settings, so a client that already reads the settings needs no separate call. The value is a caption only: it is neither the portal address nor the white-label logo text of the header, which is returned by GET api/2.0/settings/whitelabel/logotext.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The greeting title of the portal, or the localized default caption when the portal has no title of its own	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getIsDefaultGreetingSettings

BooleanWrapper getIsDefaultGreetingSettings()

GET /api/2.0/settings/greetingsettings/isdefault

Check the default greeting settings

Reports whether the current portal still shows the built-in greeting caption instead of a title of its own. The check is read-only and open to any authenticated user, with no administrative right required. It answers true while no title is stored for the portal - the state after POST api/2.0/settings/greetingsettings/restore on an installation that configures no portal name, and also after saving an empty title - and false as soon as a non-empty title has been saved. Use it together with GET api/2.0/settings/greetingsettings: that operation substitutes the localized default caption for a missing title, so only these two calls together separate a default greeting from a custom one that happens to repeat the default wording. The answer covers the greeting title alone; whether the white-label logos and logo text are still the default ones is reported by GET api/2.0/settings/whitelabel/logos/isdefault and GET api/2.0/settings/whitelabel/logotext/isdefault.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Boolean value: true if the portal has no greeting title of its own and the built-in default caption is shown	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

restoreGreetingSettings

StringWrapper restoreGreetingSettings()

POST /api/2.0/settings/greetingsettings/restore

Restore the greeting settings

Drops the custom greeting title of the current portal and puts back the title configured for the installation, which is an empty value unless the installation defines a portal name of its own. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. The change is immediate for every user of the portal and a second call changes nothing, so a retry after a failed attempt is safe. The answer is the greeting in force afterwards: the configured title when there is one, and the localized default caption when the stored title ends up empty - in that case GET api/2.0/settings/greetingsettings/isdefault starts answering true. Only the caption is touched: the portal logos and the white-label logo text keep their values and are reset separately by PUT api/2.0/settings/whitelabel/logos/restore and PUT api/2.0/settings/whitelabel/logotext/restore. To set a title instead of the default one use POST api/2.0/settings/greetingsettings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The greeting title in force after the restore, or the localized default caption when the installation configures none	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveGreetingSettings

StringWrapper saveGreetingSettings(GreetingSettingsRequestsDto)

POST /api/2.0/settings/greetingsettings

Save the greeting settings

Replaces the greeting title of the current portal with the title from the request, storing it as the portal name. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. The new caption takes effect at once for every user of the portal and the change is written to the audit trail; repeating the call with the same title leaves the portal in the same state. A missing title or one longer than 255 characters is rejected as an invalid request before the handler runs. On a cloud portal with a free or trial plan the title is also matched against the character rule configured for the installation and a title that breaks it is refused, while a paid cloud plan and a server installation apply no character check. An empty title clears the greeting: the portal falls back to the built-in default caption and GET api/2.0/settings/greetingsettings/isdefault starts answering true. What comes back is a localized confirmation message, not the stored title - read the title with GET api/2.0/settings/greetingsettings.

Parameters

Name	In	Type	Description	Notes
GreetingSettingsRequestsDto	body	GreetingSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	A localized message confirming that the greeting title has been saved	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

IPRestrictionArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsIPRestrictionsApi

getIpRestrictions

IPRestrictionArrayWrapper getIpRestrictions()

GET /api/2.0/settings/iprestrictions

Get IP restrictions

Returns the IP restriction list of the current portal - the addresses allowed to reach it, each with its id and the forAdmin flag that narrows the entry to DocSpace administrators. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. The call is read-only and honours If-None-Match: send back the ETag of an earlier answer and an unchanged list comes back as an empty not-modified response rather than a body. The list has no defined order and is empty on a portal where nobody has configured restrictions - and an empty list blocks nobody, whatever the enforcement flag says. Whether the restrictions are enforced at all is not part of this answer: read that flag with GET api/2.0/settings/iprestrictions/settings. The entries listed here apply to every user of the portal except its owner. Replace the whole list with PUT api/2.0/settings/iprestrictions; single entries cannot be added or deleted, and that update takes plain addresses rather than the IDs returned here.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The IP addresses allowed to reach the portal, each with its ID and administrators-only flag; an empty list when the portal has no restrictions	IPRestrictionArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

readIpRestrictionsSettings

IPRestrictionsSettingsWrapper readIpRestrictionsSettings()

GET /api/2.0/settings/iprestrictions/settings

Get IP restriction settings

Reports whether the IP restrictions of the current portal are enforced, as the enable flag together with the lastModified stamp of the setting. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. The call is read-only and honours If-Modified-Since: send back the Last-Modified value of an earlier answer and an unchanged setting comes back as an empty not-modified response rather than a body. The flag is false on a portal nobody has configured. A true flag on its own blocks nothing: enforcement also needs at least one stored address, which this answer does not carry - read the addresses with GET api/2.0/settings/iprestrictions - and it is skipped entirely on an installation whose configuration hides the IP security section. Even when enforced, the portal owner and the installation's own networks are let through. Change the flag with PUT api/2.0/settings/iprestrictions/settings, which replaces the address list in the same call, so resend the addresses in force when all that changes is the flag.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The enforcement flag of the IP restrictions and the date the setting was last modified	IPRestrictionsSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

IPRestrictionsSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveIpRestrictions

IpRestrictionsWrapper saveIpRestrictions(IpRestrictionsDto)

PUT /api/2.0/settings/iprestrictions

Save IP restrictions

Replaces the whole IP restriction list of the current portal with the addresses from the request and stores the enforcement flag in the same call. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. Every entry must be a single IPv4 or IPv6 address: from-to ranges and CIDR blocks are matched by the portal but cannot be stored here and are rejected as an invalid request, as is enable: true with an empty list. An omitted enable follows the list - on when addresses are sent, off when the list is empty. The replacement is written in one transaction, applies to new requests without a restart and is recorded in the audit trail; entries not repeated in the body are deleted, and sending the same body twice leaves the portal as it is. Enforcement spares the portal owner and the installation's own networks only, so a list without the caller's own address locks the remaining administrators out. The answer echoes the request rather than the stored rows - no entry IDs, and enable exactly as sent, empty when it was omitted - so read the result with GET api/2.0/settings/iprestrictions.

Parameters

Name	In	Type	Description	Notes
IpRestrictionsDto	body	IpRestrictionsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The saved addresses and enforcement flag echoed back exactly as sent, without the IDs of the stored entries	IpRestrictionsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

IpRestrictionsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateIpRestrictionsSettings

IpRestrictionsWrapper updateIpRestrictionsSettings(IpRestrictionsDto)

PUT /api/2.0/settings/iprestrictions/settings

Update IP restriction settings

Stores the enforcement flag of the IP restrictions of the current portal together with the whole address list, replacing the addresses saved before; this operation and PUT api/2.0/settings/iprestrictions are two routes to the same handler and behave identically. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. Every entry must be a single IPv4 or IPv6 address: from-to ranges and CIDR blocks are matched by the portal but cannot be stored here and are rejected as an invalid request, as is enable: true with an empty list. An omitted enable follows the list - on when addresses are sent, off when the list is empty - so the flag cannot be moved without resending the addresses that stay in force. The new state applies to new requests without a restart, is recorded in the audit trail, and sending the same body twice changes nothing further. Enforcement spares the portal owner and the installation's own networks only, so a list without the caller's own address locks the remaining administrators out. The answer echoes the request, so read the stored entries and their IDs with GET api/2.0/settings/iprestrictions.

Parameters

Name	In	Type	Description	Notes
IpRestrictionsDto	body	IpRestrictionsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The stored enforcement flag and addresses echoed back exactly as sent, without the IDs of the stored entries	IpRestrictionsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

IpRestrictionsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsLicenseApi

acceptLicense

StringWrapper acceptLicense()

POST /api/2.0/settings/license/accept

Activate a license

Activates the license staged by POST api/2.0/settings/license on this self-hosted Enterprise installation: it records that the license was accepted, promotes the staged file to the active one and rewrites the portal-wide quota and tariff from it. Upload a file first: with nothing staged and no license on disk there is nothing to activate. The caller only has to be signed in, and the activation is recorded in the audit trail. Repeating the call is safe: the acceptance stamp is written only once and the same license is simply applied again. Read the outcome from the body rather than the status code - an empty string means the license is now active, and any other string is a message explaining why it is not: no license key was found, the key is not correct, the installed edition does not match the license type, or the license is expired or too small for the current user count. The acceptance stamp survives a failed activation, so a corrected file needs nothing extra. An installation with no license path configured answers that its pricing plan does not support the option and changes nothing. The operation stays reachable while the portal is unpaid.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	An empty string when the license is now active, or a localized sentence explaining why it was not activated	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getIsLicenseRequired

BooleanWrapper getIsLicenseRequired()

GET /api/2.0/settings/license/required

Check if a license is required

Reports whether this installation still has to be given a license file before it can be used, which is the question the setup wizard asks before offering its license upload step. No authentication is needed, so it can be called on a portal nobody has signed in to yet, and the call is read-only. The answer is true only for a self-hosted Enterprise build whose license file is not on disk yet; an open-source or SaaS portal, a portal configured to let anyone in without an account, an installation whose configuration hides the pricing section, and one that takes its setup from cloud-image metadata all answer false. A false answer therefore does not mean the portal is licensed - it also covers every build that needs no license at all. Nothing here describes a license already in place, neither its due date nor whether the editing service still accepts it, and the answer turns to false only once a staged file has been activated by POST api/2.0/settings/license/accept, not when it is uploaded. The operation stays reachable while the portal is unpaid.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	`true` when this Enterprise installation still needs a license file, `false` when one is already active or the build needs none	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

refreshLicense

BooleanWrapper refreshLicense()

GET /api/2.0/settings/license/refresh

Refresh the license

Re-reads the license file of this self-hosted Enterprise installation and rewrites the portal-wide quota and tariff from it, so a file replaced on disk or a renewal issued by the vendor takes effect without a restart. A license staged by POST api/2.0/settings/license is promoted to the active one here as well, but the usual first-time order is upload and then POST api/2.0/settings/license/accept; this operation is for later refreshes. The caller only has to be signed in - no administrator right is checked. Despite the GET, the call rewrites stored data, and it is idempotent: repeating it applies the same license again. The editing service is asked to confirm the license as part of the check, and the license it reports must match the file. The answer is true when the license was applied and false on an installation with no license path configured at all, such as a SaaS or open-source portal, where nothing is read and nothing changes. A missing or unreadable file, a mismatched customer or edition, and an editing service that rejects the license all fail the call instead of answering false. The operation stays reachable while the portal is unpaid.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	`true` when the license file was re-read and the portal quota and tariff rewritten from it, `false` on an installation that has no license path configured	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

uploadLicense

StringWrapper uploadLicense(Files)

POST /api/2.0/settings/license

Upload a license

Takes the license file of this self-hosted Enterprise installation as multipart/form-data and stages it for activation; only the first entry of Files is read and the rest are ignored. The file is validated but not put in force here - follow with POST api/2.0/settings/license/accept to activate it, and until then the portal keeps the license it already had. The caller must be a DocSpace administrator, or hold a wizard or administrator confirmation link while the setup wizard is still unfinished; after the wizard is complete such a link alone is refused. An earlier staged file is overwritten, so the upload can be repeated safely. The answer is a localized sentence, not a structured result: Uploaded successfully on its own, or the same words plus the date since when support and updates are not covered, because a file already past its due date is still accepted. A request carrying no file, and a license whose start date has not arrived yet, are rejected as invalid; a file that cannot be read as a license, carries no customer id or signature, or was issued for the other edition fails the call. Whether the editing service accepts it is only checked at activation.

Parameters

Name	In	Type	Description	Notes
Files	form	List (binary)	The license file, sent as `multipart/form-data`. Only the first entry is read and the rest are ignored, and a request carrying none is refused with 400. A file that cannot be read as a license, that carries no customer id or signature, or that was issued for the other edition fails the call; one whose start date has not arrived yet is refused, while one already past its due date is still accepted. Staging only stores the file - `POST api/2.0/settings/license/accept` puts it in force - and a file staged earlier is overwritten.	[required]

Responses

Status code	Description	Type	Response headers
200	A localized confirmation that the file was staged, carrying the date support and updates ended when the license is already overdue	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request carried no license file, or the license does not start until a later date	-	-
403	The caller is not a DocSpace administrator, or a confirmation link was used after the setup wizard had already been completed	-	-
405	The installation has no license path configured, so it cannot be given a license file	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

SettingsLoginSettingsApi

getLoginSettings

LoginSettingsWrapper getLoginSettings()

GET /api/2.0/settings/security/loginsettings

Get login settings

Returns the brute-force protection of the sign-in form for the current portal: how many failed attempts are tolerated, how long the window they are counted in lasts, and how long an offender stays blocked. The caller needs the portal-settings right of a DocSpace administrator; members without it are refused, and anonymous callers are not admitted. The operation is read-only and honours If-Modified-Since: send back the Last-Modified value of an earlier answer and unchanged settings come back as an empty not-modified response rather than a body. checkPeriod and blockTime are counted in seconds. A portal nobody has configured tolerates 5 failed attempts inside a window of 60 seconds and blocks for 60 seconds, and reports isDefault true; the flag turns false as soon as any of the three values differs from that. The answer describes the portal-wide policy only: it does not say which accounts or addresses are blocked at the moment, while a lockout that has already happened is recorded in the login history and can be read with GET api/2.0/security/audit/login/filter. Change the numbers with PUT api/2.0/settings/security/loginsettings, or put them back with DELETE api/2.0/settings/security/loginsettings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The brute-force protection settings of the portal: the tolerated attempts, the counting window and the block in seconds, and whether they match the shipped defaults	LoginSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

LoginSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

setDefaultLoginSettings

LoginSettingsWrapper setDefaultLoginSettings()

DELETE /api/2.0/settings/security/loginsettings

Reset login settings

Puts the brute-force protection of the sign-in form back to what the portal shipped with: 5 tolerated failed attempts, a counting window of 60 seconds and a block of 60 seconds. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. The operation takes no parameters and overwrites whatever was configured before without asking, so read the current numbers with GET api/2.0/settings/security/loginsettings first if they are worth keeping. Only the setting is reset: sign-ins already blocked stay blocked until the block they were given runs out, and the attempt counters running for other users are left alone. The reset is portal-wide, applies to attempts made from now on, is recorded in the audit trail, and calling it twice changes nothing further. The restored numbers also decide when the sign-in form starts asking for a captcha, which it does one attempt before the block. The answer is the restored settings, with isDefault true. Store numbers of your own with PUT api/2.0/settings/security/loginsettings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The brute-force protection settings restored to the shipped defaults	LoginSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

LoginSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateLoginSettings

LoginSettingsWrapper updateLoginSettings(LoginSettingsRequestDto)

PUT /api/2.0/settings/security/loginsettings

Update login settings

Replaces the brute-force protection of the sign-in form for the whole portal: attemptCount failed attempts inside a rolling window of checkPeriod seconds, after which the offender is blocked for blockTime seconds. All three values are replaced together and each has to be between 1 and 9999, so read the current ones with GET api/2.0/settings/security/loginsettings before changing only one of them; a value outside the range is rejected as an invalid request. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. Failed attempts are counted per user name and client address, so one member's lockout leaves the rest of the portal signing in normally, and a blocked pair is refused even once the password is finally correct. The new numbers apply to attempts made from now on and leave counters and blocks already running as they are. The change is recorded in the audit trail, and the answer is the stored settings with the flag that says whether they still match the shipped defaults.

Parameters

Name	In	Type	Description	Notes
LoginSettingsRequestDto	body	LoginSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The brute-force protection settings as they were stored, with the flag that says whether they match the shipped defaults	LoginSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

LoginSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsMessagesApi

enableAdminMessageSettings

StringWrapper enableAdminMessageSettings(TurnOnAdminMessageSettingsRequestDto)

POST /api/2.0/settings/messagesettings

Enable or disable administrator messages

Switches on or off the contact form the sign-in page offers a visitor who cannot get into the portal, and which delivers their message to the portal administrators. The caller needs the portal-settings right of a DocSpace administrator - the portal owner and a DocSpace administrator qualify, any other member is refused. Send the new state as turnOn: true publishes the form, false hides it. The change covers the whole portal, applies to the next sign-in page without a restart, is recorded in the audit trail, and repeating the call with the same value leaves the portal as it is. What comes back is a localized confirmation message rather than the stored flag - read the flag as enableAdmMess from GET api/2.0/settings, which needs no token. That flag is also forced on while the portal's payment has lapsed, so it can report true on a portal where the form was switched off here. The form itself posts to POST api/2.0/settings/sendadmmail and this setting gates nothing else: the notifications administrators receive as portal members are subscribed separately with POST api/2.0/settings/notification.

Parameters

Name	In	Type	Description	Notes
TurnOnAdminMessageSettingsRequestDto	body	TurnOnAdminMessageSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	A localized message confirming that the administrator message setting has been saved	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

sendAdminMail

StringWrapper sendAdminMail(AdminMessageSettingsRequestsDto)

POST /api/2.0/settings/sendadmmail

Send a message to the administrator

Sends a message from someone who cannot get into the portal to its administrators - the contact form the sign-in page offers unauthenticated visitors. No token is needed. The form has to be published first with POST api/2.0/settings/messagesettings unless the portal's payment has lapsed, otherwise nothing is sent; enableAdmMess in GET api/2.0/settings reports whether the call is worth making. email is the address the administrators answer to and has to be a real address, and message is reduced to plain text first, so a body carrying nothing but markup counts as empty - either fault is refused with 400. When the caller is not signed in and this installation has a CAPTCHA configured, recaptchaResponse has to carry a solved challenge of the recaptchaType that GET api/2.0/settings publishes together with the site key, and a missing or stale answer refuses the call. culture picks the language of the letter. Delivery is queued and reaches the administrators subscribed to administrator notifications, so a confirmed call means accepted rather than read, and the answer is a localized confirmation. Attempts are rate limited per address and per operation, and further ones are refused with 429.

Parameters

Name	In	Type	Description	Notes
AdminMessageSettingsRequestsDto	body	AdminMessageSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	A localized message confirming that the message has been queued for the portal administrators	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The email address is malformed, or the message is empty once its markup is stripped	-	-
429	Too many contact attempts came from the same address within the rate-limit window	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

sendJoinInviteMail

StringWrapper sendJoinInviteMail(AdminMessageBaseSettingsRequestsDto)

POST /api/2.0/settings/sendjoininvite

Send an invitation email

Sends an invitation email with a join link to the address in the request - the self-registration the sign-in page's register link performs. No token is needed. The portal has to publish a trusted-domain policy first, saved with POST api/2.0/settings/maildomainsettings: without one there is nothing to join and every caller alike is answered with 405 - the same condition GET api/2.0/settings reports as enabledJoin. email has to be a real address written in ASCII rather than an internationalized one, must not already belong to a portal member, and, when the policy names domains rather than accepting all of them, has to end with one of them - each of those faults is refused with 400. culture picks the language of the letter. The invitation is not an account: the invitee becomes a member only after following the link, and the role it grants, user or room administrator, follows the trusted-domain settings and drops to user once the portal's paid places are taken. Where the installation caps invitations, an accepted call spends one of those counted by invitationLimit, and only about a dozen calls from one address in two minutes are accepted. What comes back is a localized confirmation.

Parameters

Name	In	Type	Description	Notes
AdminMessageBaseSettingsRequestsDto	body	AdminMessageBaseSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	A localized message confirming that the invitation with the join link has been sent	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The email address is malformed or internationalized, lies outside the trusted domains, or already belongs to a member of the portal	-	-
403	The portal is not accepting requests while it is being restored, transferred or encrypted	-	-
405	The portal publishes no trusted-domain policy, so it has nothing to join	-	-
429	Too many invitation requests came from the same network address	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

NotificationChannelStatusWrapper

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsNotificationsApi

getNotificationChannels

NotificationChannelStatusWrapper getNotificationChannels()

GET /api/2.0/settings/notification/channels

Get notification channels

Lists the ways this installation can deliver a notification, each as the internal name of the channel together with isEnabled: email.sender for letters and telegram.sender for Telegram messages. The list describes the installation and the portal rather than the calling user, so every member gets the same answer, and the call is read-only. Any signed-in member may ask for it, whatever its role, and no permission is demanded. A channel appears only when the notification service of the running installation is configured with a sender of that name, so the list can be shorter than the two names above, and an empty list means that configuration names no channel this build implements. email.sender is reported as enabled whenever it is listed, while telegram.sender is reported as enabled only while the portal has a Telegram bot name and token stored, which is what POST api/2.0/settings/authservice writes. An enabled channel says nothing about the caller: a member also has to connect their own Telegram account, for which GET api/2.0/settings/telegram/link hands out the link and GET api/2.0/settings/telegram/check reports the outcome. Which kinds of notification a member receives is a separate setting, read with GET api/2.0/settings/notification/{type}.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The notification channels this installation can deliver through, each with the flag that says whether it is enabled	NotificationChannelStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getNotificationSettings

NotificationSettingsWrapper getNotificationSettings(type)

GET /api/2.0/settings/notification/{type}

Check notification availability

Reports whether one kind of notification is switched on for the calling user, taking the kind as the integer type in the route: 0 the new-item badges the Files responses carry, 1 the room activity letters, 2 the daily feed digest, 3 the periodic tips letters. The answer describes the caller's own account only - there is no way to read another member's settings - and the call is read-only and safe to repeat. Every signed-in member reads its own settings: the portal owner, a DocSpace administrator, a room administrator, a user and a guest are all accepted, and no permission is demanded. Badges come back switched on for an account that has not changed them, while the kinds 1, 2 and 3 come back switched off until they are switched on with POST api/2.0/settings/notification. What comes back is the kind that was asked for together with isEnabled. A type outside 0-3 is not recognised and the call fails instead of falling back to a default. The rooms silenced one by one are listed by GET api/2.0/settings/notification/rooms, and the delivery channels of the installation by GET api/2.0/settings/notification/channels.

Parameters

Name	In	Type	Description	Notes
type	path	NotificationType	The kind of notification being asked about. A value outside the defined set fails the call rather than falling back to a default.	[required] [example: `0`] [enum: `0`, `1`, `2`, `3`]

Responses

Status code	Description	Type	Response headers
200	The notification kind that was asked for together with the flag that says whether it is switched on for the calling user	NotificationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

NotificationSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomsNotificationSettings

RoomsNotificationSettingsWrapper getRoomsNotificationSettings()

GET /api/2.0/settings/notification/rooms

Get muted rooms

Returns the rooms the calling user has silenced, as the disabledRooms list of their identifiers. The list describes the caller's own account only, the call is read-only, and an empty list means nothing is silenced. Every signed-in member reads its own list, whatever its role - owner, administrator, user or guest - and no permission is demanded. The identifiers come back the way POST api/2.0/settings/notification/rooms stored them, in the order they were added and without paging; they are kept as opaque values, so both the numeric identifier of a portal room and the string identifier of a room on a connected third-party account appear here, and an identifier stays in the list after the room itself is deleted. While a room is on this list its activity is left out of the hourly room digest and of the daily feed, the letters that room would send at once are not sent, and its new-item counters are hidden from the Files responses. Silencing a room changes nothing for its other members. The kinds of notification this list is applied to are switched with POST api/2.0/settings/notification.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The identifiers of the rooms the calling user has silenced	RoomsNotificationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

RoomsNotificationSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

setNotificationSettings

NotificationSettingsWrapper setNotificationSettings(NotificationSettingsRequestsDto)

POST /api/2.0/settings/notification

Set notification status

Switches one kind of notification on or off for the calling user: send the kind as type - 0 the new-item badges, 1 the room activity letters, 2 the daily feed digest, 3 the periodic tips letters - together with isEnabled. The change touches the caller's own account only, and repeating the call with the same pair leaves the account as it is. Every signed-in member configures its own settings: the portal owner, a DocSpace administrator, a room administrator, a user and a guest are all accepted, and no permission is demanded. With 0 switched off the Files responses report new as 0 and mark files as muted; with 1 switched off both the hourly room digest and the letters a room sends at once, such as an editor mention, stop; with 2 switched off the daily digest stops; with 3 switched off the tips letters stop. What comes back is an echo of the request rather than a re-read of the stored state, and a type outside 0-3 is echoed as well while nothing is stored, so confirm the result with GET api/2.0/settings/notification/{type}. To silence a single room instead of a whole kind use POST api/2.0/settings/notification/rooms.

Parameters

Name	In	Type	Description	Notes
NotificationSettingsRequestsDto	body	NotificationSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The notification kind and state as they were sent in the request	NotificationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

NotificationSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setRoomsNotificationStatus

RoomsNotificationSettingsWrapper setRoomsNotificationStatus(RoomsNotificationsSettingsRequestDto)

POST /api/2.0/settings/notification/rooms

Mute or unmute a room

Adds one room to the calling user's silenced list or takes it off again: mute true silences the room, false lets its notifications through. One call carries one room, so several rooms take several calls, and repeating a call with the same pair changes nothing. The room is named by roomsId and kept as an opaque value: the numeric identifier of a portal room and the string identifier of a room on a connected third-party account are both accepted, and neither the room's existence nor the caller's access to it is checked, so a mistyped identifier is stored as sent. Every signed-in member manages its own list, whatever its role, and the list of another member cannot be touched. While a room is silenced its activity is left out of the hourly room digest and of the daily feed, the letters it would send at once are not sent, and its new-item counters are hidden. The Files responses stop offering the mute action on a room once badges, room activity and the daily feed are all switched off, while this call keeps working. What comes back is the whole updated list, the same shape GET api/2.0/settings/notification/rooms returns.

Parameters

Name	In	Type	Description	Notes
RoomsNotificationsSettingsRequestDto	body	RoomsNotificationsSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The identifiers of the rooms the calling user has silenced, as the list stands after the change	RoomsNotificationSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

RoomsNotificationSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsOwnerApi

sendOwnerChangeInstructions

OwnerChangeInstructionsWrapper sendOwnerChangeInstructions(OwnerIdSettingsRequestDto)

POST /api/2.0/settings/owner

Start the portal owner change

Starts handing this portal over to another of its members: the confirmation letter goes to the current owner's address, and nothing changes until the link in it is used. The owner's own email address has to be confirmed first, otherwise the call is answered with 400; GET api/2.0/people/@self reports it as activationStatus. The caller needs the portal-settings right of a DocSpace administrator, so a room administrator, an ordinary member or a guest is refused with 403, as is naming a guest in ownerId. Only the portal owner can actually start a transfer: an administrator who is not the owner, or a named user who is inactive or unknown here, gets 200 with status 0 and a localized refusal instead of an error, so read status and not the HTTP code. A started transfer answers status 1 and a message carrying the owner's address inside an HTML mailto: anchor rather than as plain text. Ownership itself does not move here; every call issues a fresh link usable for a limited period, seven days by default, and the attempt is recorded in the audit trail. Complete the transfer with PUT api/2.0/settings/owner; changing what a member may do is PUT api/2.0/people/type/{type}.

Parameters

Name	In	Type	Description	Notes
OwnerIdSettingsRequestDto	body	OwnerIdSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The outcome of the request: `status` 1 with the address the instructions were sent to, or `status` 0 with a localized refusal when the transfer cannot be started	OwnerChangeInstructionsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal owner's own email address has not been confirmed yet, so no instructions can be sent	-	-
403	The caller does not hold the portal-settings right of a DocSpace administrator, or the user named as the new owner is a guest	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

OwnerChangeInstructionsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updatePortalOwner

updatePortalOwner(OwnerIdSettingsRequestDto)

PUT /api/2.0/settings/owner

Confirm the portal owner change

Completes the portal owner change that POST api/2.0/settings/owner started, making the user named in ownerId the owner of this portal. Authorization comes from the confirmation link in that letter, not from an ordinary session: pass the link's type, key, uid and encemail parameters in the confirm request header, and check with POST api/2.0/authentication/confirm that it is still usable, because it expires after a limited period, seven days by default. A caller without such a link is refused whatever role it holds, and so is a link whose address is no longer the owner's, which is what replaying a used link looks like. The named user has to be an active member of the portal and must not be a guest. The call is mutating: a named user who is not a DocSpace administrator yet is promoted to one first, and a promotion needing a paid seat the portal lacks is refused before ownership moves. The previous owner keeps their account and role but loses the owner's rights, and the change reaches the audit trail. The answer carries no payload: read the new ownerId from GET api/2.0/settings, which needs no token. Only the new owner can start another transfer.

Parameters

Name	In	Type	Description	Notes
OwnerIdSettingsRequestDto	body	OwnerIdSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The portal owner has been changed to the user named in the request	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The user named as the new owner cannot be found in this portal, is a guest, or is not active	-	-
409	The new owner could not be given DocSpace administrator rights, so the transfer was not applied	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsQuotaApi

getUserQuotaSettings

TenantUserQuotaSettingsWrapper getUserQuotaSettings()

GET /api/2.0/settings/userquotasettings

Get the user quota settings

Returns the portal's per-user default storage quota: whether it is enabled and, if so, its size in bytes. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission); every other authenticated role, and an anonymous caller, is refused. This is a read-only, idempotent call. When enableQuota is false, the size value is not enforced and users get unlimited personal storage regardless of what it holds. The response supports conditional requests: send the standard If-Modified-Since header with the previous lastModified value, and an unchanged response comes back empty instead of resending the settings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Current per-user default storage quota settings	TenantUserQuotaSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantUserQuotaSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveAiAgentQuotaSettings

TenantAiAgentQuotaSettingsWrapper saveAiAgentQuotaSettings(QuotaSettingsRequestsDto)

POST /api/2.0/settings/aiagentquotasettings

Save the AI Agent quota settings

Sets the portal's default storage quota for AI agents, applied as the starting limit for newly created agents. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission), and on a paid SaaS tenant the portal's plan must include the statistics feature, or the call is rejected as not covered by the plan. The requested size cannot exceed the portal's own total storage quota, nor, on a Standalone install with a portal-wide quota enabled, that quota's size. Disable enforcement by passing enableQuota=false; the size is then ignored for new agents. This is a mutating, idempotent call: sending the same body again leaves the quota unchanged. It returns the saved settings, not any agent's current usage.

Parameters

Name	In	Type	Description	Notes
QuotaSettingsRequestsDto	body	QuotaSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved default AI agent storage quota settings	TenantAiAgentQuotaSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan does not include the statistics feature required for AI agent quotas	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantAiAgentQuotaSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveRoomQuotaSettings

TenantRoomQuotaSettingsWrapper saveRoomQuotaSettings(QuotaSettingsRequestsDto)

POST /api/2.0/settings/roomquotasettings

Save the room quota settings

Sets the portal's default per-room storage quota, applied to newly created rooms as their starting limit. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission), and on a paid SaaS tenant the portal's plan must include the statistics feature, or the call is rejected as not covered by the plan. The requested size cannot exceed the portal's own total storage quota, nor, on a Standalone install with a portal-wide quota enabled, that quota's size. Disable enforcement by passing enableQuota=false; the size is then ignored for new rooms. This is a mutating, idempotent call: sending the same body again leaves the quota unchanged. It returns the saved settings, not the individual rooms' current usage.

Parameters

Name	In	Type	Description	Notes
QuotaSettingsRequestsDto	body	QuotaSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved default per-room storage quota settings	TenantRoomQuotaSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan does not include the statistics feature required for room quotas	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantRoomQuotaSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setTenantQuotaSettings

TenantQuotaSettingsWrapper setTenantQuotaSettings(TenantQuotaSettingsRequestsDto)

PUT /api/2.0/settings/tenantquotasettings

Save the tenant quota settings

Sets or removes the storage quota for a given tenant. Available only on a Standalone (self-hosted) installation; on SaaS the call is always refused. Requires a DocSpace administrator, and the portal's plan must include the statistics feature or the call is rejected as not covered by the plan. Pass a non-negative quota in bytes to enable the limit for the tenant identified by tenantId, or a negative value to remove any limit. This is a mutating, idempotent call: sending the same body again leaves the quota unchanged. It returns the saved quota settings for that tenant, not its current usage.

Parameters

Name	In	Type	Description	Notes
TenantQuotaSettingsRequestsDto	body	TenantQuotaSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Saved tenant storage quota settings	TenantQuotaSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal's pricing plan does not include the statistics feature required for tenant quotas	-	-
405	The caller is not a DocSpace administrator, or the portal is not a Standalone installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TenantQuotaSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsRebrandingApi

deleteAdditionalWhiteLabelSettings

AdditionalWhiteLabelSettingsResponseWrapper deleteAdditionalWhiteLabelSettings()

DELETE /api/2.0/settings/rebranding/additional

Delete the additional white label settings

Discards the resource flags stored for the installation and brings back the built-in set, so the sample documents, the Help Center link, the Feedback and Support link, the user forum, the video guides and the license agreements are offered as they are out of the box. Requires a DocSpace administrator and a server installation with unrestricted space access; on a SaaS portal the call is refused. Unlike POST api/2.0/settings/rebranding/additional it does not need a plan that includes branding, so an installation whose subscription no longer covers it can still be reset. The call is destructive for the stored flags, which have to be set again to come back, and it is idempotent. Instead of a flag it answers the set that is now in effect, so no follow-up read is needed. The reset is installation-wide and reaches every portal, and it leaves the visibility of the About page alone. The company details are reset separately by DELETE api/2.0/settings/rebranding/company.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The built-in resource flags that are now in effect	AdditionalWhiteLabelSettingsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AdditionalWhiteLabelSettingsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

deleteCompanyWhiteLabelSettings

CompanyWhiteLabelSettingsResponseWrapper deleteCompanyWhiteLabelSettings()

DELETE /api/2.0/settings/rebranding/company

Delete the company white label settings

Discards the company details stored for the installation and brings back the built-in ONLYOFFICE name, site, email, address and phone, so the About page and the notification letters print the original vendor again. Requires a DocSpace administrator and a server installation with unrestricted space access; on a SaaS portal the call is refused. Unlike POST api/2.0/settings/rebranding/company it does not need a plan that includes branding, so an installation whose subscription no longer covers it can still be reset. The call is destructive: the previous details are not kept anywhere and have to be entered again to come back. It is idempotent, and instead of a flag it answers the details that are now in effect, so no follow-up read is needed. The reset is installation-wide and reaches every portal. The help and support links are reset separately by DELETE api/2.0/settings/rebranding/additional, and the logos and the wordmark of a single portal by the restore operations under api/2.0/settings/whitelabel.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The built-in company details that are now in effect	CompanyWhiteLabelSettingsResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CompanyWhiteLabelSettingsResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAdditionalWhiteLabelSettings

AdditionalWhiteLabelSettingsDtoWrapper getAdditionalWhiteLabelSettings()

GET /api/2.0/settings/rebranding/additional

Get the additional white label settings

Returns which of the ONLYOFFICE help and community resources the interface may offer - the sample documents, the Help Center link, the Feedback and Support link, the user forum, the video guides and the license agreements - so a client can hide the entries that are switched off. Any authenticated user may call it; no administrator permission is required, and a portal whose payment has lapsed is served as well. The call is read-only and idempotent. Each flag is true when the entry may be shown and false when it must be hidden, and isDefault tells whether the whole set is still the built-in one. The flags are installation-wide, so every portal of a server installation reports the same ones. They say nothing about the caller's own permissions, and the addresses behind the entries are not part of the answer. Change the flags with POST api/2.0/settings/rebranding/additional and reset them with DELETE api/2.0/settings/rebranding/additional.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The help and community resources the interface may offer, with the default flag	AdditionalWhiteLabelSettingsDtoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AdditionalWhiteLabelSettingsDtoWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCompanyWhiteLabelSettings

CompanyWhiteLabelSettingsDtoWrapper getCompanyWhiteLabelSettings()

GET /api/2.0/settings/rebranding/company

Get the company white label settings

Returns the company details that the About page and the notification letters print as the vendor, in the form the settings interface edits them. Any authenticated user may call it; no administrator permission is required, and a portal whose payment has lapsed is served as well. The call is read-only and idempotent. Alongside the stored fields the answer carries isLicensor, which tells whether these details belong to the vendor of the product itself, and isDefault, which tells whether they are still the built-in ONLYOFFICE ones. The values are installation-wide, so every portal of a server installation reports the same ones. The response is revalidatable: it carries Last-Modified, and sending that value back in If-Modified-Since yields an empty body while the details have not changed, which makes polling cheap. For the About page, where the built-in vendor has to be shown next to a reseller, use GET api/2.0/settings/companywhitelabel instead. Change the details with POST api/2.0/settings/rebranding/company.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The company details in effect, with the licensor and default flags	CompanyWhiteLabelSettingsDtoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CompanyWhiteLabelSettingsDtoWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getEnableWhitelabel

BooleanWrapper getEnableWhitelabel()

GET /api/2.0/settings/enablewhitelabel

Check the white label availability

Reports whether branding may be configured for the current portal at all, which is the check to make before offering the rebranding interface or calling any of the save operations under api/2.0/settings/whitelabel. Requires a DocSpace administrator. The call is read-only and idempotent. The answer is true only when both conditions hold: the branding section is not switched off in the installation configuration, and the portal's current plan includes customization. It comes back as false on a plan without branding, which is exactly the case in which POST api/2.0/settings/whitelabel/logos/save, POST api/2.0/settings/whitelabel/logos/savefromfiles and POST api/2.0/settings/whitelabel/logotext/save are refused as payment required. The restore operations do not depend on this flag and stay available, so a portal that loses branding can still be reset to the built-in logos and wordmark. The flag says nothing about the installation-wide default branding, which additionally needs a server installation with unrestricted space access, and nothing about the company details and help links under api/2.0/settings/rebranding.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	`true` when branding is enabled in this installation and included in the portal's plan	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

IsDefaultWhiteLabelLogosWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getIsDefaultWhiteLabelLogoText

IsDefaultWhiteLabelLogosWrapper getIsDefaultWhiteLabelLogoText(IsDark, IsDefault)

GET /api/2.0/settings/whitelabel/logotext/isdefault

Check the default logo text

Reports whether the current portal still uses the built-in wordmark or one that was stored for it, which is what an interface needs to decide whether a Restore action applies to the text. Requires a DocSpace administrator. The call is read-only and idempotent. The answer has the same shape as one entry of GET api/2.0/settings/whitelabel/logos/isdefault, with name fixed to logotext and default set to true while no text has been stored and to false once one has. Because GET api/2.0/settings/whitelabel/logotext falls back to ONLYOFFICE when nothing is stored, this operation is the only way to tell a portal that deliberately kept the built-in wordmark from one that saved the very same text. Pass isDefault=true to inspect the installation-wide default branding instead of this portal's. The flag turns back to true after PUT api/2.0/settings/whitelabel/logotext/restore, and to false after POST api/2.0/settings/whitelabel/logotext/save. Saving the built-in wordmark itself counts as clearing the setting, so the flag stays true in that case as well.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	A single `logotext` entry telling whether the portal still uses the built-in wordmark	IsDefaultWhiteLabelLogosWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getIsDefaultWhiteLabelLogos

IsDefaultWhiteLabelLogosArrayWrapper getIsDefaultWhiteLabelLogos(IsDark, IsDefault)

GET /api/2.0/settings/whitelabel/logos/isdefault

Check the default white label logos

Reports, slot by slot, whether the current portal still shows the built-in image or a logo that was uploaded for it, which is what an interface needs to decide where a Restore action makes sense. Requires a DocSpace administrator; the URLs themselves are public and come from GET api/2.0/settings/whitelabel/logos, which needs no authentication. The call is read-only and idempotent. Every logo slot is returned, including the notification logo that the public list leaves out, so the result has one entry more than that list. An entry gives the stable slot name in name and default set to true while the slot has never been written, and to false once an image has been stored for it, whether for the light or for the dark theme. A slot goes back to true after PUT api/2.0/settings/whitelabel/logos/restore. Pass isDefault=true to inspect the installation-wide default branding instead of this portal's. The logo text is reported separately by GET api/2.0/settings/whitelabel/logotext/isdefault.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	One entry per logo slot, telling whether the slot still holds the built-in image	IsDefaultWhiteLabelLogosArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

IsDefaultWhiteLabelLogosArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getLicensorData

CompanyWhiteLabelSettingsArrayWrapper getLicensorData()

GET /api/2.0/settings/companywhitelabel

Get the licensor data

Returns the licensor details - company name, site, support email, postal address and phone - that the About page and the notification letters print as the vendor of the installation. Any authenticated user may call it, as these details are shown in the interface to everyone; no administrator permission is required. The call is read-only and idempotent. The list holds the details currently in effect as its first item; when they have been replaced by a reseller and the replacement is not itself marked as the licensor, the built-in ONLYOFFICE details are appended as a second item, so a caller can print both the reseller and the original vendor. A single-item list therefore means that the current details are the only ones to show. The values are installation-wide rather than per-portal, so every portal of a server installation reports the same ones. The same data in the form the settings interface edits is served by GET api/2.0/settings/rebranding/company, and it is written by POST api/2.0/settings/rebranding/company.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The licensor details in effect, followed by the built-in ONLYOFFICE ones when they have been replaced	CompanyWhiteLabelSettingsArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CompanyWhiteLabelSettingsArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWhiteLabelLogoText

StringWrapper getWhiteLabelLogoText(IsDark, IsDefault)

GET /api/2.0/settings/whitelabel/logotext

Get the white label logo text

Returns the wordmark the current portal prints next to or instead of a logo image, as a bare string rather than an object. Requires a DocSpace administrator, because this is the settings view of the value; the branding a login page needs is served by GET api/2.0/settings/whitelabel/logos, which needs no authentication. The call is read-only and idempotent. When nothing has been stored for the portal, the built-in ONLYOFFICE is returned, so the answer is never empty and cannot be used to tell a custom text from the default one - GET api/2.0/settings/whitelabel/logotext/isdefault answers that question. Pass isDefault=true to read the installation-wide default wordmark instead of this portal's; without it the portal's own value is returned even when the installation carries a different default. Change the text with POST api/2.0/settings/whitelabel/logotext/save and clear it with PUT api/2.0/settings/whitelabel/logotext/restore. The value is stored as it was typed, at most 40 characters long, and is not translated for the caller's language, so the same wordmark is returned for every user of the portal.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The wordmark stored for the portal, or the built-in `ONLYOFFICE` when none is set	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WhiteLabelItemArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWhiteLabelLogos

WhiteLabelItemArrayWrapper getWhiteLabelLogos(IsDark, IsDefault)

GET /api/2.0/settings/whitelabel/logos

Get the white label logos

Lists the branding logo slots of the current portal together with the image URLs to render, which is what a login page, an editor or a mail template needs before any user is known. No authentication is required, and the portal is resolved from the address the request is made to. The call is read-only and idempotent. Each item carries the slot as a number in type, its stable name in name, the size the image is fitted to in size (width and height in pixels), and the URLs in path. When isDark is passed, only the matching theme is filled in, light for false and dark for true; when it is omitted both are filled in and dark comes back empty for the slots that have no separate dark image. The notification slot is not part of this list, as it is derived from the login-page logo and used only in letters. Pass isDefault=true to read the installation-wide default logos instead of this portal's. To learn which slots are still untouched use GET api/2.0/settings/whitelabel/logos/isdefault.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The logo slots of the portal, each with its target size and the URLs of the light and dark images	WhiteLabelItemArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

restoreWhiteLabelLogoText

BooleanWrapper restoreWhiteLabelLogoText(IsDark, IsDefault)

PUT /api/2.0/settings/whitelabel/logotext/restore

Restore the white label logo text

Clears the wordmark stored for the current portal, so the built-in ONLYOFFICE is printed again next to or instead of the logo images. Requires a DocSpace administrator. Unlike POST api/2.0/settings/whitelabel/logotext/save it does not need a plan that includes branding, so a portal whose subscription no longer covers branding can still be reset. The call is destructive for the stored text, which is not kept anywhere and has to be typed again to come back, and it is idempotent: true comes back both when a text was cleared and when there was none. Logo images are left untouched and have their own PUT api/2.0/settings/whitelabel/logos/restore. Pass isDefault=true to reset the installation-wide default wordmark instead of this portal's, which only a server installation allows. After the call GET api/2.0/settings/whitelabel/logotext reports ONLYOFFICE and GET api/2.0/settings/whitelabel/logotext/isdefault reports default as true. The wordmark is the only setting this operation touches, so the company details and the help links of the installation are left as they are.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the portal prints the built-in wordmark again	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow default branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

restoreWhiteLabelLogos

BooleanWrapper restoreWhiteLabelLogos(IsDark, IsDefault)

PUT /api/2.0/settings/whitelabel/logos/restore

Restore the white label logos

Drops every logo uploaded for the current portal and brings back the built-in images, so the portal looks unbranded again on the login page, in the left menu, in the editors and in letters. Requires a DocSpace administrator. Unlike the two save operations it does not need a plan that includes branding, so a portal whose subscription no longer covers it can still be reset. The call is destructive: the stored image files are deleted and cannot be recovered from the portal, only re-uploaded with POST api/2.0/settings/whitelabel/logos/save. It is idempotent and answers true both when logos were removed and when there was nothing to remove. All slots are reset together; there is no way to restore a single one. For this portal the picture kept for the older mail templates is reset along with the logos, while the logo text is left as it is and has its own PUT api/2.0/settings/whitelabel/logotext/restore. Pass isDefault=true to reset the installation-wide default branding instead, which only a server installation allows. Confirm the result with GET api/2.0/settings/whitelabel/logos/isdefault.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the portal shows the built-in logos again	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow default branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveAdditionalWhiteLabelSettings

BooleanWrapper saveAdditionalWhiteLabelSettings(AdditionalWhiteLabelSettingsWrapper)

POST /api/2.0/settings/rebranding/additional

Save the additional white label settings

Stores which of the ONLYOFFICE help and community resources the interface offers: the sample documents, the Help Center link, the Feedback and Support link, the user forum, the video guides and the license agreements. The whole set is replaced by the settings object of the request, so send every flag, not only the changed ones - a flag left out is stored as off. A request without that object is rejected as an invalid request. Requires a DocSpace administrator, a server installation with unrestricted space access and a plan that includes branding, which GET api/2.0/settings/enablewhitelabel reports; on a SaaS portal the call is refused. The flags are installation-wide, so the change reaches every portal of that installation. The call is mutating and idempotent, and answers true. Only the visibility of these entries is controlled here, not the addresses behind them. Read the result back with GET api/2.0/settings/rebranding/additional and undo it with DELETE api/2.0/settings/rebranding/additional.

Parameters

Name	In	Type	Description	Notes
AdditionalWhiteLabelSettingsWrapper	body	AdditionalWhiteLabelSettingsWrapper		[optional]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the resource flags have been stored for the installation	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request carries no settings object	-	-
403	The caller is not a DocSpace administrator, or the installation does not allow branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveCompanyWhiteLabelSettings

BooleanWrapper saveCompanyWhiteLabelSettings(CompanyWhiteLabelSettingsWrapper)

POST /api/2.0/settings/rebranding/company

Save the company white label settings

Stores the company details - name, site, support email, postal address and phone - that the About page and the notification letters print as the vendor. The whole set is replaced by the settings object of the request, so send every field, not only the changed ones; a request without that object, or with an email or a site that is not a valid value, is rejected as an invalid request. Requires a DocSpace administrator, a server installation with unrestricted space access and a plan that includes branding, which GET api/2.0/settings/enablewhitelabel reports; on a SaaS portal the call is refused. The values are installation-wide, so the change reaches every portal of that installation. Two fields are not taken from the request: the licensor flag is always stored as false, and hiding the About page is silently kept off unless the plan allows it. The call is mutating and idempotent, and answers true. Read the result back with GET api/2.0/settings/rebranding/company and undo it with DELETE api/2.0/settings/rebranding/company.

Parameters

Name	In	Type	Description	Notes
CompanyWhiteLabelSettingsWrapper	body	CompanyWhiteLabelSettingsWrapper		[optional]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the company details have been stored for the installation	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request carries no settings object, or the email or the site is not a valid value	-	-
403	The caller is not a DocSpace administrator, or the installation does not allow branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveWhiteLabelLogoText

BooleanWrapper saveWhiteLabelLogoText(IsDark, IsDefault, WhiteLabelRequestsDto)

POST /api/2.0/settings/whitelabel/logotext/save

Save the white label logo text

Sets the wordmark that the portal prints next to or instead of a logo image, on the login page, in the editors and in notification letters. Only logoText from the request body is used here, and it is limited to 40 characters; a longer value is rejected as an invalid request. Sending an empty or blank text, or exactly the built-in ONLYOFFICE, clears the setting instead of storing it, which has the same effect as PUT api/2.0/settings/whitelabel/logotext/restore. Requires a DocSpace administrator and a plan that includes branding, which GET api/2.0/settings/enablewhitelabel reports; otherwise the call is refused as payment required. The call is mutating and idempotent: the previous text is overwritten and true comes back. Logo images are not touched - they are saved by POST api/2.0/settings/whitelabel/logos/save - and the text is not rendered into them. Pass isDefault=true to write the installation-wide default wordmark instead of this portal's, which only a server installation allows. Read the stored value back with GET api/2.0/settings/whitelabel/logotext.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]
WhiteLabelRequestsDto	body	WhiteLabelRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the logo text has been stored for the portal	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow default branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveWhiteLabelSettings

BooleanWrapper saveWhiteLabelSettings(IsDark, IsDefault, WhiteLabelRequestsDto)

POST /api/2.0/settings/whitelabel/logos/save

Save the white label logos

Replaces the branding images of the current portal with the ones sent in the request, so that the logos on the login page, in the left menu, in the editors and in letters come from this portal. Every entry of logo names a logo slot in its key - the numeric type published by GET api/2.0/settings/whitelabel/logos - and carries the light-theme and the dark-theme image in light and dark. An image is either a data:image/png;base64,... payload (png, jpg and svg are accepted) or the name of a file already uploaded to the temporary store; a slot left out of the request keeps its image. The dark image is stored only for the slots that have a dark variant, that is 1, 2, 6, 7 and 8, and is ignored for the favicon and the editor logos; saving slot 2 also rebuilds the notification logo 8 from it. Requires a DocSpace administrator and a plan that includes branding, which GET api/2.0/settings/enablewhitelabel reports; otherwise the call is refused as payment required. It answers true and is undone by PUT api/2.0/settings/whitelabel/logos/restore. With isDefault=true it writes the installation-wide default branding instead, which only a server installation allows. Uploaded files go to POST api/2.0/settings/whitelabel/logos/savefromfiles.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]
WhiteLabelRequestsDto	body	WhiteLabelRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the submitted logos have been stored for the portal	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow default branding to be edited	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveWhiteLabelSettingsFromFiles

BooleanWrapper saveWhiteLabelSettingsFromFiles(IsDark, IsDefault)

POST /api/2.0/settings/whitelabel/logos/savefromfiles

Save the logos from files

Replaces the branding images of the current portal with the files sent as multipart/form-data, which is the way to upload image files directly instead of embedding them as base64 in POST api/2.0/settings/whitelabel/logos/save. The form field names are not used: each file is routed by its own name, which has to start with the numeric logo slot published by GET api/2.0/settings/whitelabel/logos and end with the image extension, as in 2.png; a name that also contains dark, as in 2.dark.png, is stored as the dark-theme image of that slot. Slots that get no file keep the image they have, and a dark file is ignored for the favicon and the editor logos, which have no dark variant. A request that carries no file at all is rejected. Requires a DocSpace administrator and a plan that includes branding, which GET api/2.0/settings/enablewhitelabel reports; otherwise the call is refused as payment required. It answers true, overwrites in place and is undone by PUT api/2.0/settings/whitelabel/logos/restore. With isDefault=true it writes the installation-wide default branding, which only a server installation allows.

Parameters

Name	In	Type	Description	Notes
IsDark	query	Boolean	Which theme the answer is filled in for: `true` fills the dark image only, `false` the light one only. Omitting it fills both, leaving the dark one empty for the slots that have no separate dark image.	[optional] [example: `true`]
IsDefault	query	Boolean	Whether the installation-wide default branding is addressed instead of this portal own. Writing the default branding is only allowed on a self-hosted installation; elsewhere it is refused with 403.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	Always `true` once the uploaded files have been stored as the portal logos	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not a DocSpace administrator, or the installation does not allow default branding to be edited	-	-
409	The request carried no file to store as a logo	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SettingsSSOApi

getDefaultSsoSettingsV2

SsoSettingsV2Wrapper getDefaultSsoSettingsV2()

GET /api/2.0/settings/ssov2/default

Get the default SSO settings

Returns the built-in SSO configuration a portal starts from: empty identity provider and service provider sections with the stock SAML settings already filled in (HTTP-POST binding, transient name ID format, RSA-SHA1 signing, AES-128 encryption), the default attribute mapping of givenName, sn and mail, the Single Sign-on login label, new accounts typed as user, and SSO switched off. Use it as the template for a new configuration: fill in the identity provider entity ID, sign-in URL and certificates, then send the result to POST api/2.0/settings/ssov2. The values are the same for every portal and do not depend on what is currently saved, nothing is written, and the call is safe to repeat. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, and the portal plan has to include Single Sign-On. This operation changes nothing by itself: to actually discard the configuration in use, call DELETE api/2.0/settings/ssov2, and to read what is configured now, call GET api/2.0/settings/ssov2.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The built-in SSO configuration a portal starts from	SsoSettingsV2Wrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSsoSettingsV2

SsoSettingsV2Wrapper getSsoSettingsV2()

GET /api/2.0/settings/ssov2

Get the SSO settings

Returns the SAML Single Sign-On configuration of the current portal: the identity provider endpoints and certificates, the service provider certificates, the attribute mapping, the login button label and the user type new SSO accounts get. Anonymous callers are accepted, but an unauthenticated one receives only hideAuthPage, which tells the sign-in page whether the built-in login form has to be hidden; every other field stays empty, so read the full configuration with an authenticated request. An authenticated caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, and the portal plan has to include Single Sign-On, otherwise the call is refused. The operation only reads and is safe to repeat. When the login label was never set, the response carries the built-in Single Sign-on instead of an empty string, and enableSso is null until the settings are saved for the first time. Use GET api/2.0/settings/ssov2/default for a blank configuration to start from, and GET api/2.0/settings/ssov2/constants for the values the SAML fields accept.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The current portal SSO settings; an anonymous caller gets only the hidden-login-form flag	SsoSettingsV2Wrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

SsoSettingsV2ConstantsWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSsoSettingsV2Constants

SsoSettingsV2ConstantsWrapper getSsoSettingsV2Constants()

GET /api/2.0/settings/ssov2/constants

Get the SSO settings constants

Returns every literal value the SAML fields of the SSO configuration accept, grouped by the field it belongs to: name ID formats, request bindings, signing and encryption algorithms, and what a service provider or identity provider certificate can be used for. The values are the SAML URNs and algorithm URIs themselves, so they can be written into the configuration exactly as they come back; picking one from the matching group is the point, because POST api/2.0/settings/ssov2 stores these fields as they are given and a misspelled value therefore surfaces only later, as a failing sign-in. The list is a fixed part of the product: it is the same for every portal, does not depend on the saved settings and does not change between calls within a release, so it can be cached. The operation only reads, is safe to repeat and needs nothing beyond an authenticated caller. Use it together with GET api/2.0/settings/ssov2/default, which already has the usual values set.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Every value the SAML fields accept: name ID formats, bindings, signing and encryption algorithms, and the service provider and identity provider certificate uses	SsoSettingsV2ConstantsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

resetSsoSettingsV2

SsoSettingsV2Wrapper resetSsoSettingsV2()

DELETE /api/2.0/settings/ssov2

Reset the SSO settings

Discards the SAML Single Sign-On configuration of the current portal, stores the built-in default one in its place and returns what was stored, which is the same content as GET api/2.0/settings/ssov2/default. This is destructive and cannot be undone through the API: the identity provider addresses, both certificate sets, the attribute mapping and the login label are gone and SSO is left switched off, so keep a copy of GET api/2.0/settings/ssov2 first if the configuration may be needed again. Every account that signed in through SSO is unlinked and becomes an ordinary account that keeps its data but authenticates with portal credentials from then on, and its external contacts are converted the same way. Repeating the call is harmless, as the second one stores the same defaults again. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, and the portal plan has to include Single Sign-On, otherwise the call is refused. To switch SSO off while keeping the configuration, send it back to POST api/2.0/settings/ssov2 with SSO disabled instead. The reset is recorded in the audit trail.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The default SSO configuration that is now in effect	SsoSettingsV2Wrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveSsoSettingsV2

SsoSettingsV2Wrapper saveSsoSettingsV2(SsoSettingsRequestsDto)

POST /api/2.0/settings/ssov2

Save the SSO settings

Replaces the whole SAML Single Sign-On configuration of the current portal with the one passed as a JSON object in serializeSettings, and returns the configuration as it was stored. The payload is a complete configuration rather than a patch: fields left out are stored empty, so send back a changed copy of GET api/2.0/settings/ssov2, or start from GET api/2.0/settings/ssov2/default. The identity provider entity ID and sign-in URL are required, the sign-in and sign-out URLs have to be absolute http or https addresses, and the attribute mapping has to name the fields for first name, last name and email; otherwise nothing is saved. The caller has to be allowed to edit portal settings (portal owner or DocSpace admin), and the portal plan has to include Single Sign-On. Some values are normalised on the way in: a usersType other than 1 (room admin), 3 (DocSpace admin) or 4 (user) becomes 4, an empty login label becomes Single Sign-on, and a longer one is cut to 100 characters. Saving with SSO switched off unlinks every existing SSO account and turns it into an ordinary one; switching SSO back on later does not restore those links. The change is recorded in the audit trail.

Parameters

Name	In	Type	Description	Notes
SsoSettingsRequestsDto	body	SsoSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The SSO settings as they were stored, with the login label and the user type normalised	SsoSettingsV2Wrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The serialized settings are empty or do not contain an SSO configuration object	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

EnabledModuleArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsSecurityApi

getEnabledModules

EnabledModuleArrayWrapper getEnabledModules()

GET /api/2.0/settings/security/modules

Get enabled modules

Lists the portal modules the calling user can currently open, each as an id holding the module's product class name and a title holding its display name, both HTML-encoded. Any signed-in member may call this; anonymous callers are not admitted. The operation is read-only and takes no parameters, and the list is specific to the caller: modules hidden for this portal, and modules whose access rules exclude the caller, are left out, and sub-modules nested under another module are never listed. Entries follow the portal's own module order rather than an alphabetical one. An empty list means the installation registers no such modules at all - the case on DocSpace, where the classic modules do not exist - and is not a failure. The identifiers here are display-oriented class names, not the GUIDs the access-settings operations work with, so do not feed them to GET api/2.0/settings/security/{id}, which expects a module GUID.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The portal modules the calling user can open, each with its product class name and its display name, in the portal's own module order	EnabledModuleArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getIsProductAdministrator

ProductAdministratorWrapper getIsProductAdministrator(productid, userid)

GET /api/2.0/settings/security/administrator

Check product administrator

Reports whether one user administers one portal module, as the identifiers asked about plus an administrator flag. Both productid and userid are query parameters and both are required; the all-zero product GUID asks about the portal itself rather than about a single module. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. The operation is read-only. The flag is true when the user belongs to the DocSpace administrator group or to the module's own group, so a portal-wide administrator is reported as an administrator of every module, whatever the module identifier says. Identifiers that name no user and no group are answered with false instead of a failure, so a false does not prove the user exists. The verdict is read out of group membership alone and says nothing about whether the module is enabled for this portal, which GET api/2.0/settings/security/{id} reports. Use GET api/2.0/settings/security/administrator/{productid} to list everyone who administers a module, and PUT api/2.0/settings/security/administrator to change the membership.

Parameters

Name	In	Type	Description	Notes
productid	query	UUID (uuid)	The module being asked about, by module GUID. The all-zero GUID asks about the portal itself rather than a single module.	[required] [example: `00000000-0000-0000-0000-000000000000`]
userid	query	UUID (uuid)	The account being asked about, by portal user ID. An ID that names no account is answered as a plain negative rather than a failure, so a negative answer does not prove the account exists.	[required] [example: `00000000-0000-0000-0000-000000000000`]

Responses

Status code	Description	Type	Response headers
200	The module and the user asked about together with the flag that says whether that user administers the module	ProductAdministratorWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ProductAdministratorWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPasswordSettings

PasswordSettingsWrapper getPasswordSettings()

GET /api/2.0/settings/security/password

Get password settings

Returns the password policy of the current portal: the minimum length together with the flags that demand an uppercase letter, a digit and a special symbol, plus the regular expressions a client can check a password against before sending it anywhere. Any signed-in member may read it, and it is also reachable with the parameters of a confirmation link, so an invited user or one resetting a password can validate the new password before having a session; a portal whose payment has lapsed still answers. The operation is read-only and honours If-Modified-Since: send back the Last-Modified value of an earlier answer and an unchanged policy comes back as an empty not-modified response rather than a body. A portal nobody has configured requires 8 characters with all three flags off. Whatever the policy says, the portal refuses a password longer than 30 characters, a ceiling this answer does not carry. Change the policy with PUT api/2.0/settings/security/password.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The portal password policy: the minimum length, the uppercase, digit and special-symbol requirements, and the regular expressions a client can validate against	PasswordSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

PasswordSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getProductAdministrators

EmployeeArrayWrapper getProductAdministrators(productid)

GET /api/2.0/settings/security/administrator/{productid}

Get product administrators

Lists the users who administer the portal module identified by productid in the path. The all-zero GUID stands for the portal itself: the answer then covers the DocSpace administrator group together with every product group, and includes the portal owner, who administers everything by default. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. productid has to be a GUID, and one that names no group is answered with an empty list rather than a failure. The operation is read-only and returns whole user profiles, a heavier answer than a membership check, and a user who belongs to more than one of the groups asked about is listed once per group. Entries arrive in group order, the DocSpace administrator group first, the list is neither paged nor filterable, and a promotion made through the sibling PUT shows up here at once. Use GET api/2.0/settings/security/administrator to test a single user against a single module, and PUT api/2.0/settings/security/administrator to promote or demote somebody.

Parameters

Name	In	Type	Description	Notes
productid	path	UUID (uuid)	The module the operation acts on, by module GUID. The all-zero GUID stands for the portal itself rather than for a single module, and a GUID that names no module group is answered with an empty result instead of a failure.	[required] [example: `00000000-0000-0000-0000-000000000000`]

Responses

Status code	Description	Type	Response headers
200	The users who administer the module asked about, or the portal-wide administrators when the all-zero identifier is used	EmployeeArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

EmployeeArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWebItemSecurityInfo

BooleanWrapper getWebItemSecurityInfo(id)

GET /api/2.0/settings/security/{id}

Check module availability

Answers whether the module with the given identifier is available to the calling user right now, as a single boolean. id is the module GUID and travels in the path; a value that is not a GUID does not match the route at all. Any signed-in member may call this; anonymous callers are not admitted. The operation is read-only and its answer is specific to the caller: true means a module with that identifier is registered in this portal, is visible, and the caller is allowed to read it, while false covers every other case - the module is not registered here, it is hidden for this portal, or the caller is outside the users and groups allowed to open it. A false therefore does not tell those apart, and an unknown identifier is reported as unavailable instead of failing. Read the allow-list behind the decision with GET api/2.0/settings/security, list the modules the caller can actually open with GET api/2.0/settings/security/modules, and change access with PUT api/2.0/settings/security.

Parameters

Name	In	Type	Description	Notes
id	path	UUID (uuid)	The identifier of the object the operation acts on, as the listing operation of that kind of object reports it. It has to match the shape the route declares - a GUID where the route is typed as one - since a value of another shape does not match the route at all and is answered as not found.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	Whether the module is registered, visible and readable by the calling user - false covers a module that is not registered here as well as one the caller may not open	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

ProductAdministratorWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWebItemSettingsSecurityInfo

SecurityArrayWrapper getWebItemSettingsSecurityInfo(ids)

GET /api/2.0/settings/security

Get module access settings

Reports how access to the portal's own modules is configured: for every module identifier sent in ids, whether access is restricted at all and which users and groups are allowed to open the module. Send the identifiers as repeated ids query values; each one has to be a GUID, and anything else is rejected as an invalid request. Omitting ids asks about every module registered in the portal, which on a DocSpace installation is none, so the answer is then an empty list rather than a failure. Any signed-in member may call this; anonymous callers are not admitted. The operation is read-only and answers one entry per identifier, in the order the identifiers were sent. enabled is false for a module nobody has ever configured, groups and users name the subjects the rule was stored for, and isSubItem marks a module that hangs under another one. Users the caller is not allowed to see are left out of users, so the same module can come back with different lists for different callers. Change any of this with PUT api/2.0/settings/security.

Parameters

Name	In	Type	Description	Notes
ids	query	List	The modules to report on, each given as a GUID and sent as a repeated query value. An entry that is not a GUID fails the whole request as invalid. Leaving the list out asks about every module registered in the portal, which on a DocSpace installation is none, so the answer is then empty rather than complete.	[optional] [example: `["00000000-0000-0000-0000-000000000000"]`]

Responses

Status code	Description	Type	Response headers
200	The access configuration of every module identifier asked about: the enabled flag, the allowed groups, the allowed users the caller may see, and the sub-module flag	SecurityArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SecurityArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

setAccessToWebItems

SecurityArrayWrapper setAccessToWebItems(WebItemsSecurityRequestsDto)

PUT /api/2.0/settings/security/access

Set access to modules in bulk

Switches several portal modules on or off in one call: items carries an entry per module, its key the module GUID and its value the new enabled flag. The caller needs the portal-settings right of a DocSpace administrator, and the call is answered with 403 on an open portal, where everyone is admitted and per-module rules would mean nothing. Every key has to be a GUID; anything else is rejected as an invalid request, and a module listed twice is applied once, from its first entry. This operation carries no subject list of its own: switching a product module on restores the users and groups it was last restricted to, while every other case is stored as a plain allow or deny for everyone, so use PUT api/2.0/settings/security when the allow-list itself has to change. The batch is recorded in the audit trail as one list update rather than module by module. The answer is the resulting configuration of every module listed, in the shape GET api/2.0/settings/security returns.

Parameters

Name	In	Type	Description	Notes
WebItemsSecurityRequestsDto	body	WebItemsSecurityRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The resulting access configuration of every module listed in the request	SecurityArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Per-module access cannot be configured on an open portal, or the caller lacks the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SecurityArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setProductAdministrator

ProductAdministratorWrapper setProductAdministrator(SecurityRequestsDto)

PUT /api/2.0/settings/security/administrator

Set product administrator

Promotes a portal member to administrator of one module, or takes that role away, according to the administrator flag; the all-zero product GUID targets the DocSpace administrator role, which covers the whole portal. The caller needs the portal-settings right of a DocSpace administrator, and granting the portal-wide role additionally requires being the portal owner - anyone else is refused with 403. A free cloud plan does not offer the option at all and answers 402, as does a promotion for which no paid seat is left, since promoting a guest or a plain member turns them into a paid one. Taking the portal-wide role away also removes the member from every product group. The change is immediate, portal-wide, recorded in the audit trail, and sending the same body twice changes nothing further; it never creates a user, so invite the member first. The answer echoes the identifiers and the flag as stored - re-read membership with GET api/2.0/settings/security/administrator.

Parameters

Name	In	Type	Description	Notes
SecurityRequestsDto	body	SecurityRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The module, the user and the administrator flag as they were stored	ProductAdministratorWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
402	The portal plan does not offer product administrators, or no paid seat is left for the member being promoted	-	-
403	Only the portal owner can grant or revoke the portal-wide administrator role	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setWebItemSecurity

SecurityArrayWrapper setWebItemSecurity(WebItemSecurityRequestsDto)

PUT /api/2.0/settings/security

Set module access

Replaces the access rules of one portal module: id names the module, enabled says whether it may be opened, and subjects lists the users and groups the rule is stored for. The caller needs the portal-settings right of a DocSpace administrator, and the call is answered with 403 on an open portal, where everyone is admitted and per-module rules would mean nothing. id has to be a GUID; anything else is rejected as an invalid request. The rules stored before are dropped rather than extended, so send the full list of subjects every time. Watch the empty cases: leaving subjects out applies enabled to everyone, while an empty subjects array is stored as access for everyone whatever enabled says. The change is recorded in the audit trail unless subjects was left out entirely. The answer is the module's resulting configuration as a single-entry list, in the shape GET api/2.0/settings/security returns. To switch several modules at once use PUT api/2.0/settings/security/access.

Parameters

Name	In	Type	Description	Notes
WebItemSecurityRequestsDto	body	WebItemSecurityRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The resulting access configuration of the module, as a single-entry list	SecurityArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Per-module access cannot be configured on an open portal, or the caller lacks the portal-settings right of a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

SecurityArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updatePasswordSettings

PasswordSettingsWrapper updatePasswordSettings(PasswordSettingsRequestsDto)

PUT /api/2.0/settings/security/password

Update password settings

Replaces the password policy of the whole portal with the four values sent: minLength and the three flags that demand an uppercase letter, a digit and a special symbol. There is no partial update - a flag left out of the body is stored as false - so read the current policy with GET api/2.0/settings/security/password and send it back with your change applied. The caller needs the portal-settings right of a DocSpace administrator, otherwise the call is refused. minLength has to sit between the floor the installation is configured with, 8 characters unless it was changed, and the ceiling of 30; anything outside is rejected as an invalid request. The new policy applies to passwords set from now on: existing passwords keep working until their owners change them, and nobody is asked to renew. The change is portal-wide, recorded in the audit trail, and sending the same body twice changes nothing further. The answer is the stored policy with its regular expressions.

Parameters

Name	In	Type	Description	Notes
PasswordSettingsRequestsDto	body	PasswordSettingsRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The password policy as it was stored, including the regular expressions a client can validate against	PasswordSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The requested minimum length is outside the range the installation allows	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

PasswordSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsStatisticsApi

getSpaceUsageStatistics

UsageSpaceStatItemArrayWrapper getSpaceUsageStatistics(id)

GET /api/2.0/settings/statistics/spaceusage/{id}

Get the space usage statistics

Returns the storage space used by one portal module, broken down per data category the module tracks (for example per room type), together with a human-readable size and whether the category is disabled. Requires Owner or DocSpaceAdmin (the EditPortalSettings permission). id identifies the module by the same GUID the portal's module catalog uses; a module that does not exist, or one that does not report space usage at all, returns an empty list rather than an error. This is a read-only, idempotent call, and the list is not paginated. Sizes are already formatted as display strings (for example 1.5 GB), not raw byte counts.

Parameters

Name	In	Type	Description	Notes
id	path	UUID (uuid)	The identifier of the object the operation acts on, as the listing operation of that kind of object reports it. It has to match the shape the route declares - a GUID where the route is typed as one - since a value of another shape does not match the route at all and is answered as not found.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	Per-category space usage statistics for the requested module	UsageSpaceStatItemArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

UsageSpaceStatItemArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SettingsStorageApi

getAllBackupStorages

StorageArrayWrapper getAllBackupStorages(Dump)

GET /api/2.0/settings/storage/backup

Get the backup storages

Returns the storages that can hold portal backups, with the one the saved backup schedule writes to marked as current and its parameters filled in from that schedule; when no schedule is saved, or when the schedule stores backups somewhere else than a third-party provider, none of the entries is current. Each entry has the same shape as in GET api/2.0/settings/storage: identifier, title, the authentication keys the provider expects, and isSet telling whether those keys are filled in on the server. Pass dump=true to read the schedule of the whole server instead of the one of the current portal, which only makes sense on a server installation. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, and on an installation that is not a server one the call is also refused unless backup is available there. Nothing is written and the call is safe to repeat. This operation says nothing about where the portal data itself lives; the backup schedule is configured through the backup API, and the storage of the documents through PUT api/2.0/settings/storage.

Parameters

Name	In	Type	Description	Notes
Dump	query	Boolean	Whether the schedule of the whole server is read instead of the one of the current portal. It only changes which schedule marks an entry as `current`; the list of storages itself is the same either way, and the flag makes sense only on a self-hosted installation.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The storages that can hold portal backups, with the scheduled one marked as current	StorageArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit portal settings, or backup is not available on this installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

StorageArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAllCdnStorages

StorageArrayWrapper getAllCdnStorages()

GET /api/2.0/settings/storage/cdn

Get the CDN storages

Returns the storages that can serve the static content of the portal through a content delivery network, which is the subset of the providers of GET api/2.0/settings/storage that offer a CDN of their own. The entries have the same shape as in the storage listing: identifier and title, the authentication keys the provider expects, isSet telling whether those keys are filled in on the server, and current marking the CDN the portal uses now. Keys of the current entry come from the saved CDN settings and keys of the others from the provider configuration. An empty list means the build ships no CDN-capable provider, and a list where nothing is current means the portal serves its static content itself. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, on a server installation with an unrestricted access space. Nothing is written and the call is safe to repeat. Use PUT api/2.0/settings/storage/cdn to select a CDN and DELETE api/2.0/settings/storage/cdn to stop using one.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The storages that can serve as the portal CDN, with the one in use marked as current	StorageArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit portal settings, or this installation does not allow changing the storage	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

StorageArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAllStorages

StorageArrayWrapper getAllStorages()

GET /api/2.0/settings/storage

Get the portal storages

Returns the third-party storages the installation can keep portal data in, the providers the build ships with, such as Amazon S3, Google Cloud Storage or Rackspace. The built-in local storage is not among them: when none of the entries is current, the portal data sits in the local storage. Each entry carries the storage identifier and title, the authentication keys the provider expects, isSet telling whether those keys are already filled in on the server, and current marking the one the portal uses right now. Keys of the current storage are read from the saved settings, keys of the others from the provider configuration, so a value that was never configured comes back empty. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, and the installation has to be a server one whose access space is not restricted; otherwise the call is refused with 403. Nothing is written and the call is safe to repeat. Use PUT api/2.0/settings/storage to switch the storage, DELETE api/2.0/settings/storage to go back to the local one, and GET api/2.0/settings/storage/cdn or GET api/2.0/settings/storage/backup for the CDN and backup targets.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The storages available to the portal, each marked as configured and as currently in use	StorageArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit portal settings, or this installation does not allow changing the storage	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

StorageArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAmazonS3Regions

AmazonS3RegionArrayWrapper getAmazonS3Regions()

GET /api/2.0/settings/storage/s3/regions

Get the Amazon S3 regions

Returns the Amazon regions the server knows about, each with its system name such as eu-central-1, the display name to show a user, and the partition details the region belongs to: partition name, DNS suffix, the pattern its region names match and the template its host names are built from. This is static reference data compiled into the server rather than portal configuration: nothing is read from the settings, nothing is written, the answer is the same for every portal and changes only when the server is updated, so it can be cached by the caller. Use the system name of an entry as the region value in props when configuring an Amazon S3 storage with PUT api/2.0/settings/storage, PUT api/2.0/settings/storage/cdn or a backup schedule, and prefer picking a value from here over typing one, because a region the server does not know cannot be reached. Any authenticated caller may read the list, no portal-settings permission is asked for, and the result is neither paginated nor filtered.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The Amazon regions known to this installation	AmazonS3RegionArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

AmazonS3RegionArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getStorageProgress

DoubleWrapper getStorageProgress()

GET /api/2.0/settings/storage/progress

Get the storage migration progress

Returns how far the current portal has got in moving its data to another storage, as a percentage from 0 to 100. The migration itself is started by PUT api/2.0/settings/storage or DELETE api/2.0/settings/storage, which put the portal into the migrating state; poll this operation until the value reaches 100, then the portal is served from the new storage. A value of -1 means storage migration is not offered on this installation, which is the case for every portal that is not a server one. Ask for the progress only once a migration has actually been started: for a portal whose migration the server does not remember, the call fails instead of answering with a zero. The response carries the percentage only, without the error flag the migration service reports internally, so a value that stops advancing is a reason to check the portal state with GET api/2.0/portal rather than proof of progress. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, and the call is accepted even when the portal payment has lapsed. Nothing is written and the call is safe to repeat.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Migration progress as a percentage, or -1 where storage migration is not offered	DoubleWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

DoubleWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

resetCdnToDefault

resetCdnToDefault()

DELETE /api/2.0/settings/storage/cdn

Reset the CDN storage settings

Drops the CDN configuration of the current portal, module and saved credentials alike, so that the static content is served by the portal itself again. Nothing is uploaded or migrated, no state change is queued and the call gives back no body: only the settings are cleared, and files already copied to the content delivery network are left where they are, to be removed in the provider's own console if that is wanted. The change takes effect for links built after it, so a page that is already open may keep pointing at the CDN until it is reloaded. Repeating the call is harmless, because clearing an empty configuration does nothing. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, on a server installation with an unrestricted access space. Use GET api/2.0/settings/storage/cdn to see what is configured now and PUT api/2.0/settings/storage/cdn to select a CDN again; the portal storage of the documents is untouched by this operation and is reset with DELETE api/2.0/settings/storage instead.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The CDN configuration has been cleared and static content is served by the portal again	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit portal settings, or this installation does not allow changing the storage	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

resetStorageToDefault

resetStorageToDefault()

DELETE /api/2.0/settings/storage

Reset the storage settings

Drops the third-party storage configuration of the current portal, module and saved credentials alike, and starts an asynchronous migration of the portal data back into the built-in local storage. The portal moves into the migrating state and stays unavailable until the transfer ends, so follow it with GET api/2.0/settings/storage/progress; the call itself returns as soon as the migration has been handed to the storage service and gives back no body. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, on a server installation with an unrestricted access space. This is a mutating and slow operation rather than a destructive one: documents are copied back rather than deleted, but the credentials of the previous storage are gone from the settings and have to be sent again with PUT api/2.0/settings/storage to switch back. Repeating the call while a migration is running starts another one, so poll instead. Resetting the storage is also the step that makes POST api/2.0/settings/encryption/start possible, since encryption only covers the local storage.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The storage configuration has been cleared and migration back to the local storage has started	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit portal settings, or this installation does not allow changing the storage	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateCdnStorage

CdnStorageSettingsWrapper updateCdnStorage(StorageRequestsDto)

PUT /api/2.0/settings/storage/cdn

Update the CDN storage

Selects the content delivery network that serves the static content of the portal and saves the credentials it needs: module is the identifier of one of the entries of GET api/2.0/settings/storage/cdn, and props carries that provider's authentication keys as name and value pairs. The provider has to be available on the server, which the isSet flag of the listing tells, otherwise the request is rejected as invalid. Sending the module the portal already uses changes nothing and returns the saved settings as they are. Any other module is saved and the upload of the static content is handed to the storage service; the settings come back only when that hand-over succeeds, a failure being reported as a server error. Unlike the portal storage this has no progress operation, so there is nothing to poll: the content appears on the CDN once the service has copied it. Only static content is affected here, never documents; for those use PUT api/2.0/settings/storage. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, on a server installation with an unrestricted access space. The response is the stored CDN configuration.

Parameters

Name	In	Type	Description	Notes
StorageRequestsDto	body	StorageRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The saved CDN configuration; the upload of the static content has been handed to the storage service	CdnStorageSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The requested CDN module is not configured on this installation	-	-
403	The caller may not edit portal settings, or this installation does not allow changing the storage	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

CdnStorageSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateStorage

StorageSettingsWrapper updateStorage(StorageRequestsDto)

PUT /api/2.0/settings/storage

Switch the portal storage

Points the current portal at another storage and saves the credentials it needs: module is the identifier of one of the storages listed by GET api/2.0/settings/storage, and props carries that provider's authentication keys as name and value pairs, for example the bucket, region and access key of an Amazon S3 storage. The provider has to be available on the server, which the isSet flag of the listing tells, otherwise the request is rejected as invalid. Sending the module the portal already uses changes nothing and returns the saved settings as they are. Any other module starts an asynchronous migration of the portal data: the portal moves into the migrating state and stays unavailable until the transfer ends, so follow it with GET api/2.0/settings/storage/progress and do not send a second switch while it runs. The caller needs the permission to edit portal settings, which in practice means the portal owner or a DocSpace admin, on a server installation with an unrestricted access space. The response is the stored configuration, module and properties, not the state of the migration. To return to the built-in local storage call DELETE api/2.0/settings/storage, and for the CDN use PUT api/2.0/settings/storage/cdn.

Parameters

Name	In	Type	Description	Notes
StorageRequestsDto	body	StorageRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The saved storage configuration; migration of the portal data to it has been started	StorageSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The requested storage module is not configured on this installation	-	-
403	The caller may not edit portal settings, or this installation does not allow changing the storage	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

StorageSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsTFASettingsApi

getTfaAppCodes

TfaAppCodeArrayWrapper getTfaAppCodes()

GET /api/2.0/settings/tfaappcodes

Get the TFA backup codes

Returns the one-time backup codes of the current user's authenticator-application credential, each with the flag that says whether it has been spent. A backup code is accepted in place of a code from the application when signing in, and every code works exactly once, so this list is what a member falls back on after losing access to their authenticator. Any authenticated member may call it, always for their own account: there is no way to read someone else's codes. The authenticator method has to be enabled on the portal and an application has to be linked to the account already, otherwise the call answers 405; link one through GET api/2.0/settings/tfaapp/confirm and POST api/2.0/settings/tfaapp/validate. Accounts flagged as outsiders are refused. This is a read-only, idempotent call: the codes are generated once, when the application is first linked, and the whole set is replaced by PUT api/2.0/settings/tfaappnewcodes. The default configuration issues five codes of six characters, and a portal may be configured for a different number and length.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The caller's backup codes, each with the flag showing whether it has already been used	TfaAppCodeArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
405	The authenticator method is not enabled on this portal, or the caller has no application linked	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TfaAppCodeArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTfaConfirmData

TfaConfirmDataWrapper getTfaConfirmData()

GET /api/2.0/settings/tfaapp/confirm

Get TFA confirmation data

Returns the confirmation link the current user has to follow to pass the portal's two-factor authentication step, together with the confirmation cookie that link depends on. Any authenticated member may call it, always for their own account, and TFA has to be required for that account by the portal policy already, otherwise the response body is empty. Which link comes back depends on the method. With the SMS method it is a phone activation link while the account has no activated mobile number and a phone authorization link afterwards, and only url is filled in. With the authenticator-application method the response also carries cookieName and cookieValue, and the call mutates state by issuing a fresh confirmation key and setting that cookie; the link then points at activation while no application is linked, or after the previous link was reset, and at re-verification once one is linked. Hand the code obtained through that flow to POST api/2.0/settings/tfaapp/validate. The portal-wide policy behind all of this is read with GET api/2.0/settings/tfaapp.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The confirmation link for the caller's TFA step, with the cookie filled in for the authenticator method	TfaConfirmDataWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TfaConfirmDataWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTfaSettings

TfaSettingsArrayWrapper getTfaSettings()

GET /api/2.0/settings/tfaapp

Get the TFA settings

Lists the two-factor authentication methods this portal offers, with the state of each one. The list carries at most two entries: sms, present only when the SMS method is enabled in the portal's configuration, and app, present only when the authenticator-application method is enabled there, so an empty list means neither method is offered here. Any authenticated member may call it, and what it returns is the portal-wide policy, not the caller's own linked credential. This is a read-only, idempotent call. For every entry enabled says whether that method is the current policy, available says whether it can actually be switched on (for sms that also requires a configured SMS provider), trustedIps lists the addresses and ranges exempt from the challenge, and mandatoryUsers and mandatoryGroups list the accounts that have to pass it even from a trusted address. Change the policy with PUT api/2.0/settings/tfaapp, and read the caller's own backup codes with GET api/2.0/settings/tfaappcodes.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The TFA methods the portal offers, with the portal-wide state of each	TfaSettingsArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TfaSettingsArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

tfaAppGenerateSetupCode

TfaSetupCodeWrapper tfaAppGenerateSetupCode()

GET /api/2.0/settings/tfaapp/setup

Generate the TFA setup code

Issues the secret the current user has to enter in an authenticator application before the authenticator-application method can be used, both as a scannable QR-code image and as a key for manual entry. The call is reachable only with a confirmation token carrying the TfaActivation role, obtained from GET api/2.0/settings/tfaapp/confirm or from the login flow; an ordinary bearer token is refused. The authenticator method has to be enabled on the portal and be its current policy, and the account must have no application linked yet: for an already-linked account the call answers 405, so reset the credential first with PUT api/2.0/settings/tfaappnewapp. Accounts flagged as outsiders are refused. Repeating the call is safe and hands back the same secret for the account, so the QR code and the manual key always describe one and the same credential. qrCodeSetupImageUrl is a base64 data: URL of a PNG image, and account is the label the application will show. Finish the setup by sending a code from the application to POST api/2.0/settings/tfaapp/validate.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The account label, the manual entry key and the QR-code image for linking an authenticator application	TfaSetupCodeWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
405	The authenticator method is not enabled on this portal, or the account already has an application linked	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TfaSetupCodeWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

tfaValidateAuthCode

BooleanWrapper tfaValidateAuthCode(TfaValidateRequestsDto)

POST /api/2.0/settings/tfaapp/validate

Validate the TFA code

Verifies a two-factor authentication code for the account named in the confirmation link being used, and completes that account's pending TFA step. The call is reachable only with a confirmation token carrying the TfaActivation or TfaAuth role, issued by GET api/2.0/settings/tfaapp/confirm or by the login flow; an ordinary bearer token is refused. Both a code from the authenticator application and one of the account's unused backup codes are accepted, and a backup code is spent by the check. The call mutates state: it signs the account in, clears the confirmation cookie so the link cannot be replayed, and on the very first activation it generates the backup codes later returned by GET api/2.0/settings/tfaappcodes. Pass session=true to keep that sign-in for the browser session only instead of a persistent one. It answers true only for that first activation and false when an application was already linked. A wrong code is rejected as an invalid request, and further attempts are refused once the portal's login attempt limit is reached. The call also works while the portal's payment is overdue.

Parameters

Name	In	Type	Description	Notes
TfaValidateRequestsDto	body	TfaValidateRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	`true` when the code completed a first activation and backup codes were generated, `false` when an application was already linked	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

unlinkTfaApp

StringWrapper unlinkTfaApp(TfaRequestsDto)

PUT /api/2.0/settings/tfaappnewapp

Unlink the TFA application

Detaches the authenticator application from an account, so that the account has to link a new one before it can sign in again. id has to name an existing account: an empty or unknown value is refused. Passing the caller's own ID resets their own credential and returns the activation link they should follow next; passing another member's ID is allowed for the portal owner only, and every other caller, a DocSpace administrator included, is refused. The account has to have an application linked and the authenticator method has to be enabled on the portal, otherwise the call answers 405. The call is destructive: the account's backup codes are dropped together with the credential and all of its sessions are signed out. For another member the portal also emails them that their TFA was reset, and the answer is then an empty string. The portal-wide policy is not touched, so TFA stays required and the account sets up an application again through GET api/2.0/settings/tfaapp/confirm; lift the requirement for everyone with PUT api/2.0/settings/tfaapp.

Parameters

Name	In	Type	Description	Notes
TfaRequestsDto	body	TfaRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The activation link when the caller reset their own application, or an empty string when another member's was reset	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not the portal owner, or the account cannot be resolved from `id`	-	-
405	The authenticator method is not enabled on this portal, or the account has no application linked	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TfaAppCodeArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateTfaAppCodes

TfaAppCodeArrayWrapper updateTfaAppCodes()

PUT /api/2.0/settings/tfaappnewcodes

Regenerate the TFA backup codes

Replaces the current user's one-time backup codes with a freshly generated set and returns it. Use it once the previous codes have been spent or may have leaked: the whole old set stops being accepted the moment this call succeeds, so store the new codes before leaving the response. Any authenticated member may call it, always for their own account. The authenticator method has to be enabled on the portal and an application has to be linked to the account already, otherwise the call answers 405, and accounts flagged as outsiders are refused. The call mutates state and is not idempotent: every invocation issues another set and discards the one before it, so a retry after a timeout returns codes different from those the first attempt generated. The codes come back unused, five of them of six characters with the default configuration, and a portal may be configured for a different number and length. Read the current set without changing it through GET api/2.0/settings/tfaappcodes. The authenticator secret itself is untouched, so the linked application keeps working.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The newly generated backup codes, all unused, replacing the caller's previous set	TfaAppCodeArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
405	The authenticator method is not enabled on this portal, or the caller has no application linked	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateTfaSettings

BooleanWrapper updateTfaSettings(TfaRequestsDto)

PUT /api/2.0/settings/tfaapp

Update the TFA settings

Sets the portal-wide two-factor authentication policy: type 1 switches on the SMS method, 2 switches on the authenticator application, and 0 turns TFA off, as does any unknown value. The two methods are mutually exclusive, so switching one on switches the other off. The caller has to be the portal owner or a DocSpace administrator; other members are refused, and a request that names the owner's account in id or in mandatoryUsers is refused unless id carries the caller's own account. trustedIps takes single addresses, inclusive ranges and CIDR blocks, and an unparseable entry is rejected as an invalid request; accounts listed in mandatoryUsers or mandatoryGroups still have to pass the challenge even from a trusted address. Switching a method on is disruptive: it resets the portal's authentication cookies, so every session on the portal, the caller's own included, has to sign in again. The answer is true when a method was switched on and false when TFA was turned off. Use PUT api/2.0/settings/tfaappwithlink instead to receive the caller's own confirmation link in the same step.

Parameters

Name	In	Type	Description	Notes
TfaRequestsDto	body	TfaRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	`true` when the SMS or the authenticator method was switched on, `false` when TFA was turned off	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
405	The requested method is not enabled on this portal, or the SMS method has no configured provider	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateTfaSettingsLink

StringWrapper updateTfaSettingsLink(TfaRequestsDto)

PUT /api/2.0/settings/tfaappwithlink

Update TFA settings with a link

Applies the same portal-wide two-factor authentication change as PUT api/2.0/settings/tfaapp and additionally returns the confirmation link the caller needs to pass the new challenge, so an administrator who has just switched TFA on can go straight to setting it up for themselves. The caller has to be the portal owner or a DocSpace administrator, and a request that names the owner's account in id or in mandatoryUsers is refused unless id carries the caller's own account. Every effect of the plain call applies here too: the methods are mutually exclusive, type 0 turns TFA off, trustedIps and the two mandatory lists behave the same way, and switching a method on resets the portal's authentication cookies, so all sessions have to sign in again. The answer is an empty string whenever there is no link to hand out: when the request turned TFA off, and when the caller is exempt from the challenge, most often because their own address is in the trustedIps list of that very request. The cookie the link depends on is not returned here, read it with GET api/2.0/settings/tfaapp/confirm.

Parameters

Name	In	Type	Description	Notes
TfaRequestsDto	body	TfaRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The caller's own confirmation link, or an empty string when TFA was turned off or the caller is exempt	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is neither the portal owner nor a DocSpace administrator, or is placing the owner under the policy	-	-
405	The requested method is not enabled on this portal, or the SMS method has no configured provider	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

TelegramStatusWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsTelegramApi

checkTelegram

TelegramStatusWrapper checkTelegram()

GET /api/2.0/settings/telegram/check

Check the Telegram connection

Reports whether the current user's account is linked to the portal's Telegram bot, and under which Telegram username. The bot keys must be configured for the portal beforehand with POST api/2.0/settings/authservice; until a bot is configured, linking cannot be completed and the status never reaches the linked state. Any authenticated user may call it, and only for their own account: there is no way to read another member's Telegram status. This is a read-only, idempotent call. The returned status is published as a number, where 0 means the account is not linked, 1 means it is linked, and 2 means a registration link has been issued and the portal is still waiting for the user to open it in Telegram. The username field is filled in only in state 1 and comes back empty in the other two. Start or resume linking with GET api/2.0/settings/telegram/link, and drop an established link with DELETE api/2.0/settings/telegram/link.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The current user's Telegram link state, with the username filled in only when linked	TelegramStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

linkTelegram

StringWrapper linkTelegram()

GET /api/2.0/settings/telegram/link

Get the Telegram link

Returns the personal t.me deep link that connects the current user's account to the portal's Telegram bot, so that notifications can be delivered to that user in Telegram. The bot keys must be configured for the portal beforehand with POST api/2.0/settings/authservice; without a configured bot name the response comes back empty. Any authenticated user may call it, and the link always belongs to the caller's own account. The call mutates state: unless the user still has an outstanding registration token it issues a fresh one, so calling it twice in a row hands back the same link instead of invalidating the first. That token is short-lived (20 minutes with the default configuration), and once it has expired the operation has to be called again for a new link. Linking itself is completed in Telegram, not here, so poll GET api/2.0/settings/telegram/check until its status becomes 1. Remove an established link with DELETE api/2.0/settings/telegram/link.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	A `t.me` deep link that connects the caller's account to the portal's Telegram bot	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

unlinkTelegram

BooleanWrapper unlinkTelegram()

DELETE /api/2.0/settings/telegram/link

Unlink Telegram

Removes the link between the current user's account and the portal's Telegram bot, so that this user stops receiving notifications in Telegram. Any authenticated user may call it, and only for their own account: one member cannot unlink another. Nothing has to be linked beforehand, and the call is destructive but idempotent, returning true both when a link was removed and when there was none to remove, so a retry after a timeout is safe. Only the portal-side link is dropped: the chat itself stays in the user's Telegram, and the portal's bot configuration is untouched, so the other members keep their own links. Re-linking is not automatic, request a new link with GET api/2.0/settings/telegram/link and confirm the result with GET api/2.0/settings/telegram/check. Delivery over the other notification channels is unaffected; the channels enabled for the portal are listed by GET api/2.0/settings/notification/channels.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Always `true` once the caller has no link to the Telegram bot	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

SettingsWebhooksApi

createWebhook

WebhooksConfigWrapper createWebhook(CreateWebhooksConfigRequestsDto)

POST /api/2.0/settings/webhook

Create a webhook

Creates a webhook subscription for the current portal: a target URL that the portal calls with a signed JSON payload whenever one of the subscribed events happens. The target is checked before anything is stored, so it has to be an absolute http or https address outside the installation's own network, and it has to answer a HEAD request with a success code, redirects not being followed. secretKey is mandatory here, has to satisfy the portal password rules published by GET api/2.0/settings/security/password, and signs the payloads; it does not appear in any response. triggers is a bitmask of the subscribed events with 0 standing for all of them; a flag the caller's role may not use is rejected, so take the allowed set from GET api/2.0/settings/webhook/triggers. ssl=true additionally demands an https target with a valid certificate, while ssl=false leaves the certificate unchecked. Set targetId to deliver events about a single entity only. A subscription fires only for events its creator is allowed to see, and only while it is enabled. Any role except Guest may create one, and each call adds another subscription rather than replacing an existing one.

Parameters

Name	In	Type	Description	Notes
CreateWebhooksConfigRequestsDto	body	CreateWebhooksConfigRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The created webhook subscription, without its secret key	WebhooksConfigWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The target URL is unusable or unreachable, or the secret key or a trigger flag was rejected	-	-
403	The caller is a `Guest`, or a non-admin caller while the developer tools are restricted	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

enableWebhook

WebhooksConfigWrapper enableWebhook(UpdateWebhooksConfigRequestsDto)

PUT /api/2.0/settings/webhook/enable

Switch a webhook on or off

Switches one webhook subscription on or off, leaving the rest of its parameters as they are. Only id and enabled are read from the body: name, uri, secretKey, ssl, triggers and targetId are demanded by the schema but ignored here, so change any of them with PUT api/2.0/settings/webhook instead. Switching a subscription on re-checks what is already stored, probing the saved URL with a HEAD request and re-validating the saved secret against the current portal password rules, and the call is refused with 400 when either fails: a subscription whose target has gone away, or whose secret predates a tightening of the password rules, cannot be switched on until it is updated. Switching one off is not validated. While a subscription is off its events are dropped rather than queued, so nothing arrives from that period once it is switched on again. A DocSpaceAdmin may switch any subscription in the portal, anyone else only their own, and a Guest is refused. The response carries the subscription in its new state, and repeating the call changes nothing further.

Parameters

Name	In	Type	Description	Notes
UpdateWebhooksConfigRequestsDto	body	UpdateWebhooksConfigRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The webhook subscription in its new state, without its secret key	WebhooksConfigWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The saved target no longer answers, or the saved secret no longer passes the password rules	-	-
403	The subscription belongs to another member, or the caller may not use webhooks at all	-	-
404	No webhook subscription with this ID exists in the portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebhooksConfigWithStatusArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getTenantWebhooks

WebhooksConfigWithStatusArrayWrapper getTenantWebhooks()

GET /api/2.0/settings/webhook

Get the portal webhooks

Returns the webhook subscriptions of the current portal, each together with the outcome of its most recent delivery. The portal owner and a DocSpaceAdmin see every subscription in the portal, while a RoomAdmin or a User sees only the ones they created themselves, so the same call answers differently depending on who asks. A Guest may not use webhooks at all and is refused, and so is any non-admin caller while the portal keeps the developer tools restricted, which GET api/2.0/settings/devtoolsaccess reports. Every entry pairs the stored configuration with status, the HTTP status code the target answered on the last attempt, where 0 means nothing has been delivered yet, while the secret key is not part of the response. The list is neither paginated nor ordered, and an empty list simply means no subscription exists for the caller. Nothing is written and the call is safe to repeat. Create a subscription with POST api/2.0/settings/webhook, and inspect single deliveries with GET api/2.0/settings/webhooks/log.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The webhook subscriptions visible to the caller, each with the status of its last delivery	WebhooksConfigWithStatusArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is a `Guest`, or a non-admin caller while the developer tools are restricted	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWebhookTriggers

WebhookTriggerArrayWrapper getWebhookTriggers()

GET /api/2.0/settings/webhook/triggers

Get the webhook triggers

Returns the catalogue of events a webhook subscription can listen to, in the order the portal presents them: user events, then group, file, folder, room, form and agent ones. Each entry carries the event name as it appears in a payload, such as file.created, the bit value to put into the triggers bitmask of a subscription, and available, telling whether the caller's own role may subscribe to that event at all: a User cannot subscribe to the creation of users, groups or rooms, for instance, while a RoomAdmin can. Add the bit values of the wanted events together to build triggers; the entry named * has the value 0 and stands for every event, so it is used on its own rather than added. Events unavailable to the caller are listed all the same, but passing one to POST api/2.0/settings/webhook or PUT api/2.0/settings/webhook is rejected as an invalid request. This is fixed reference data: the same for every portal, not paginated, changing only with the product version, and readable by any authenticated caller, a Guest included. Nothing is written.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The triggers a webhook may subscribe to, each marked available for the caller's role or not	WebhookTriggerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebhookTriggerArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWebhooksLogs

WebhooksLogArrayWrapper getWebhooksLogs(deliveryFrom, deliveryTo, hookUri, configId, eventId, groupStatus, userId, trigger, count, startIndex)

GET /api/2.0/settings/webhooks/log

Get the webhook delivery log

Returns the delivery records of the portal webhooks, one record per attempt, carrying the trigger, the request and response headers and bodies, the HTTP status the target answered and the delivery moment, the last two staying empty while an attempt is still on its way. Records come newest first and are paged with startIndex and count, at most 100 at a time, while the number of records matching the filter is reported as total beside the response. Filters combine with AND: deliveryFrom and deliveryTo bound the delivery moment, hookUri matches the subscription URL exactly, configId picks one subscription, eventId one single record, groupStatus keeps only the answered status classes it names with 0 meaning no status filter, and trigger narrows to one event with 0 meaning all of them. userId filters by who created the subscription rather than by who caused the event, and for a caller who is not a DocSpaceAdmin it is forced to the caller, so a non-admin only ever sees deliveries of their own subscriptions. A Guest is refused. Nothing is written.

Parameters

Name	In	Type	Description	Notes
deliveryFrom	query	Date (date-time)	The earliest delivery moment a record may carry. Records of attempts still on their way have no delivery moment yet and fall outside any bound set here.	[optional] [example: `2024-01-15T10:30:00Z`]
deliveryTo	query	Date (date-time)	The latest delivery moment a record may carry. All the filters combine with AND, so it narrows whatever the other ones already kept.	[optional] [example: `2024-01-15T10:30:00Z`]
hookUri	query	String	The subscription target address, matched in full rather than as a prefix. Filtering by `configId` is the reliable way to pick one subscription, since several may share an address.	[optional] [example: `https://example.com/webhook`]
configId	query	Integer (int32)	The subscription whose deliveries are kept, by the `id` that `GET api/2.0/settings/webhook` reports.	[optional] [example: `1`]
eventId	query	Integer (int32)	A single delivery record, by its own identifier. It narrows the answer to that one record, which is how a client follows up a retry it queued earlier.	[optional] [example: `1`]
groupStatus	query	WebhookGroupStatus	The classes of answered status to keep, as a bitmask; 0 keeps every record whatever the target answered.	[optional] [example: `NotSent`] [enum: `0`, `1`, `2`, `4`, `8`, `16`]
userId	query	UUID (uuid)	The member whose subscriptions the records belong to, by portal user ID - who created the subscription, not who caused the event. For a caller who is not a DocSpace administrator it is overwritten with the caller own ID, so such a caller never sees another member deliveries whatever is sent here.	[optional] [example: `{}`]
trigger	query	WebhookTrigger	The single event kind to keep; 0 keeps every kind. It names one trigger rather than a mask of several, unlike the `triggers` a subscription is created with.	[optional] [example: `0`] [enum: `0`, `1`, `2`, `4`, `8`, `16`, `32`, `64`, `128`, `256`, `512`, `1024`, `2048`, `4096`, `8192`, `16384`, `32768`, `65536`, `131072`, `262144`, `524288`, `1048576`, `2097152`, `4194304`, `8388608`, `16777216`, `33554432`, `67108864`, `134217728`, `268435456`, `536870912`, `1073741824`]
count	query	Integer (int32)	How many records one page may hold. The maximum is also the default, so a client that wants shorter pages has to ask for them; the number of records matching the filter comes back as `total` beside the page.	[optional] [example: `1`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many matching records to skip before the page begins, counting from the newest. Advance it by `count` to walk back through the log.	[optional] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The matching delivery records, newest first, with the total count reported beside them	WebhooksLogArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is a `Guest`, or a non-admin caller while the developer tools are restricted	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebhooksLogArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

removeWebhook

WebhooksConfigWrapper removeWebhook(id)

DELETE /api/2.0/settings/webhook/{id}

Remove a webhook

Removes one webhook subscription from the current portal for good, addressed by id in the path. Deliveries stop with it: matching events are no longer queued, and there is no undo, so a subscription dropped by mistake has to be created again with POST api/2.0/settings/webhook, which gives it a new identifier and needs a new secret key. To pause deliveries without losing the configuration, switch the subscription off with PUT api/2.0/settings/webhook/enable instead. A DocSpaceAdmin may remove any subscription in the portal, anyone else only the ones they created, and a Guest may not use webhooks at all. The response repeats the subscription as it was just before the removal, so the caller can record what disappeared, again without the secret key. An identifier that no longer exists gives 404, which is what a second removal of the same subscription answers as well, so a repeated call is harmless but reports the state truthfully rather than pretending to succeed.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The identifier of the object the operation acts on, as the listing operation of that kind of object reports it. It has to match the shape the route declares - a GUID where the route is typed as one - since a value of another shape does not match the route at all and is answered as not found.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The removed webhook subscription, as it was just before the removal	WebhooksConfigWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The subscription belongs to another member, or the caller may not use webhooks at all	-	-
404	No webhook subscription with this ID exists in the portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebhooksLogArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

retryWebhook

WebhooksLogWrapper retryWebhook(id)

PUT /api/2.0/settings/webhook/{id}/retry

Retry a webhook delivery

Sends one past webhook delivery again. The id in the path is that of a delivery record from GET api/2.0/settings/webhooks/log, not of a subscription, and the payload kept in that record is sent once more to the subscription it belongs to. The work is asynchronous: a fresh delivery record is created and queued at once, and the response describes that new record, with an identifier of its own and with status and delivery not filled in yet. To learn the outcome, read GET api/2.0/settings/webhooks/log with eventId set to the returned identifier until delivery appears. The original record stays as it is, and every call queues one more attempt, so this is not safe to repeat blindly. A DocSpaceAdmin may retry any delivery in the portal, anyone else only deliveries of the subscriptions they created, and a Guest is refused. An id of 0 is rejected as an invalid request and an unknown one gives 404. The operation is rate limited, so a burst of calls is answered with 429; to retry several records use PUT api/2.0/settings/webhook/retry.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The identifier of the object the operation acts on, as the listing operation of that kind of object reports it. It has to match the shape the route declares - a GUID where the route is typed as one - since a value of another shape does not match the route at all and is answered as not found.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The newly queued delivery record, with its status and delivery moment not filled in yet	WebhooksLogWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The delivery record identifier is 0	-	-
403	The delivery belongs to another member's subscription, or the caller may not use webhooks	-	-
404	No delivery record with this ID exists in the portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebhooksLogWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

retryWebhooks

WebhooksLogArrayWrapper retryWebhooks(WebhookRetryRequestsDto)

PUT /api/2.0/settings/webhook/retry

Retry webhook deliveries

Sends a batch of past webhook deliveries again. ids holds the identifiers of delivery records from GET api/2.0/settings/webhooks/log; each of them is sent once more to the subscription it belongs to as a fresh delivery record, queued for asynchronous delivery, and the response lists those new records with status and delivery not filled in yet. Records that do not exist, and records of another member's subscription when the caller is not a DocSpaceAdmin, are skipped in silence instead of failing the call, so a response shorter than ids is the only sign that something was left out: compare the counts rather than assuming everything was queued. An empty ids list is accepted and queues nothing. Read the outcomes from GET api/2.0/settings/webhooks/log, matching the returned identifiers with eventId. Every call queues another round of attempts, and the original records stay as they are. A Guest is refused. The operation is rate limited, so a burst of calls is answered with 429. For a single record PUT api/2.0/settings/webhook/{id}/retry reports a missing or forbidden record instead of skipping it.

Parameters

Name	In	Type	Description	Notes
WebhookRetryRequestsDto	body	WebhookRetryRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The newly queued delivery records, one for every identifier that could be retried	WebhooksLogArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is a `Guest`, or a non-admin caller while the developer tools are restricted	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateWebhook

WebhooksConfigWrapper updateWebhook(UpdateWebhooksConfigRequestsDto)

PUT /api/2.0/settings/webhook

Update a webhook

Replaces the stored parameters of one webhook subscription, which is addressed by id in the body rather than in the path. Every field of the request overwrites the stored one, so a payload that leaves out enabled, ssl, triggers or targetId resets them to off, all events and no target: read the current values with GET api/2.0/settings/webhook first and send back whatever should stay. secretKey is the one exception, an empty value keeping the existing secret and a new one having to satisfy the portal password rules. The new target is validated exactly as on creation, that is it must sit outside the installation's own network and answer a HEAD request, and trigger flags the caller's role may not use are rejected. That validation runs before the subscription is looked up, so an unusable payload is refused with 400 even when no subscription with this id exists. A DocSpaceAdmin may update any subscription in the portal, anyone else only their own, and a Guest is refused. Sending the same payload twice leaves the same state. Use PUT api/2.0/settings/webhook/enable to switch a subscription on or off without touching anything else.

Parameters

Name	In	Type	Description	Notes
UpdateWebhooksConfigRequestsDto	body	UpdateWebhooksConfigRequestsDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The updated webhook subscription, without its secret key	WebhooksConfigWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The target URL is unusable or unreachable, or the secret key or a trigger flag was rejected	-	-
403	The subscription belongs to another member, or the caller may not use webhooks at all	-	-
404	No webhook subscription with this ID exists in the portal	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebPluginArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

SettingsWebpluginsApi

addWebPluginFromFile

WebPluginWrapper addWebPluginFromFile(system)

POST /api/2.0/settings/webplugins

Add a web plugin

Installs a web plugin into the current portal from an uploaded package, and switches the plugin on straight away. The package is sent as multipart/form-data with exactly one file: a .zip archive holding a config.json manifest and a plugin.js entry point, under the configured size cap of 5 MB by default. Editing the portal settings is required, so a portal owner or administrator, and the installation has to have web plugins and plugin uploading enabled in its configuration. Pass system=true to install the plugin for every portal of the installation, which is accepted on standalone installations only. The call is mutating and not idempotent: a package whose manifest name is already installed replaces the stored files and keeps the settings saved for that name, and the domains the manifest declares are added to the portal Content Security Policy. It returns the freshly installed plugin, enabled, with the url its script is served from. A portal holds up to 100 plugins by default, the manifest name has to be lower-case letters, digits, _, . or -, and the package is rejected when another installed plugin registers the same JavaScript object under a different name. List what is installed with GET api/2.0/settings/webplugins.

Parameters

Name	In	Type	Description	Notes
system	query	Boolean	Whether the plugin is installed for every portal of the installation rather than only this one. It is accepted on a self-hosted installation alone and refused with 403 elsewhere; an installation-wide plugin also hides a portal plugin that carries the same name.	[optional] [example: `false`]

Responses

Status code	Description	Type	Response headers
200	The installed web plugin, enabled, with the `url` its script is served from	WebPluginWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The uploaded package is missing, of the wrong type, too large, or its manifest is rejected	-	-
403	Web plugins or plugin uploads are switched off for the installation, or `system` was requested outside a standalone installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebPluginWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

deleteWebPlugin

deleteWebPlugin(name)

DELETE /api/2.0/settings/webplugins/{name}

Delete a web plugin

Removes a web plugin from the current portal and deletes the files of its package from storage. The name is the manifest name published by GET api/2.0/settings/webplugins, matched without regard to case. Editing the portal settings is required, so a portal owner or administrator, and the installation has to have web plugins and plugin deletion enabled in its configuration. An installation-wide plugin, the one whose system field is true, can be removed on standalone installations only. The call is destructive and cannot be undone: the state and the settings stored for the plugin are dropped along with its files, the domains its manifest declares are taken out of the portal Content Security Policy, and the connected clients are notified. Getting the plugin back means uploading its package again with POST api/2.0/settings/webplugins, and the settings it had are gone. Nothing is returned on success, and a repeated call on a name that is no longer installed is rejected as not found instead of answered as success. To keep a plugin installed but inactive, switch it off with PUT api/2.0/settings/webplugins/{name} instead.

Parameters

Name	In	Type	Description	Notes
name	path	String	The plugin to act on, by the manifest name `GET api/2.0/settings/webplugins` publishes as `name`, matched without regard to case. It is neither the localized display name nor the JavaScript object name in `pluginName`; a name that is not installed answers 404.	[required] [example: `example-plugin`]

Responses

Status code	Description	Type	Response headers
200	The web plugin and the files of its package are removed from the portal	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Web plugins or plugin deletion are switched off, the caller may not edit the portal settings, or the plugin is installation-wide outside a standalone installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWebPlugin

WebPluginWrapper getWebPlugin(name)

GET /api/2.0/settings/webplugins/{name}

Get a web plugin by name

Returns one web plugin of the current portal by its manifest name, looked up over the same set as GET api/2.0/settings/webplugins: the installation-wide plugins plus the portal's own. The name is the manifest name published in the name field of that list, matched without regard to case; it is neither the localized display name nor the JavaScript object name in pluginName, so it cannot be taken from the title shown in the interface. Any authenticated portal member may call it, no settings permission needed, and the installation has to have web plugins enabled in its configuration. The call is read-only and idempotent. The response carries the manifest data along with the state the portal stored for that plugin: enabled, the settings string, system, and the url and cssUrl a client loads it from. A name that is not installed is rejected as not found, and 403 means web plugins are switched off for the installation. Change the state of the plugin with PUT api/2.0/settings/webplugins/{name}.

Parameters

Name	In	Type	Description	Notes
name	path	String	The plugin to act on, by the manifest name `GET api/2.0/settings/webplugins` publishes as `name`, matched without regard to case. It is neither the localized display name nor the JavaScript object name in `pluginName`; a name that is not installed answers 404.	[required] [example: `example-plugin`]

Responses

Status code	Description	Type	Response headers
200	The requested web plugin with the state the portal stored for it	WebPluginWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Web plugins are switched off for the installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

WebPluginWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getWebPlugins

WebPluginArrayWrapper getWebPlugins(enabled)

GET /api/2.0/settings/webplugins

Get web plugins

Lists the web plugins available in the current portal: the plugins installed for the whole installation first, then the portal's own, with a portal plugin dropped when an installation-wide plugin already uses its name. Any authenticated portal member may call it, no settings permission needed, and the installation has to have web plugins enabled in its configuration. The call is read-only and idempotent. Pass enabled=true or enabled=false to keep only the plugins in that state, and leave the parameter out to get every plugin. Each entry carries the manifest data together with the state the portal stored for that plugin: enabled, the settings string, system for an installation-wide plugin, and the url and cssUrl a client loads the plugin from. An empty list means nothing is installed for this portal, not that plugins are switched off, which is refused with 403 instead. The list is capped at the configured maximum, 100 plugins by default, and is not paginated. For one plugin by its manifest name use GET api/2.0/settings/webplugins/{name}.

Parameters

Name	In	Type	Description	Notes
enabled	query	Boolean	Which plugins are kept: `true` the ones switched on, `false` the ones switched off. Omitting it lists every installed plugin whatever its state.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The web plugins available in the portal, the installation-wide ones first	WebPluginArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Web plugins are switched off for the installation	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateWebPlugin

updateWebPlugin(name, WebPluginRequests)

PUT /api/2.0/settings/webplugins/{name}

Update a web plugin

Switches a web plugin of the current portal on or off and stores the settings string the portal keeps for it. The plugin has to be installed already, so upload its package with POST api/2.0/settings/webplugins first, and name is its manifest name as published by GET api/2.0/settings/webplugins, matched without regard to case. Editing the portal settings is required, so a portal owner or administrator, and the installation has to have web plugins enabled in its configuration. The body replaces the stored state instead of merging into it, which makes the call idempotent; settings is required, so send {} when there is nothing to keep, and it is limited to 255 characters and stored encrypted for this portal alone. Switching the plugin on adds the domains its manifest declares to the portal Content Security Policy and switching it off takes them away again, and the connected clients are notified of the new state. Nothing is returned on success. A name that is not installed is rejected as not found, and 403 means web plugins are switched off or the caller may not edit the portal settings.

Parameters

Name	In	Type	Description	Notes
name	path	String	The plugin to change, by the manifest name `GET api/2.0/settings/webplugins` publishes as `name`, matched without regard to case. It is neither the localized display name nor the JavaScript object name in `pluginName`, so it cannot be read off the interface; a name that is not installed answers 404.	[required] [example: `example-plugin`]
WebPluginRequests	body	WebPluginRequests	The whole state the plugin is to have afterwards. It replaces what was stored instead of merging into it, so both the enabled flag and the settings have to be sent every time.	[required]

Responses

Status code	Description	Type	Response headers
200	The state and the settings of the web plugin are saved for the portal	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Web plugins are switched off for the installation, or the caller may not edit the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

ThirdPartyApi

getThirdPartyCode

StringWrapper getThirdPartyCode(provider)

GET /api/2.0/thirdparty/{provider}

Get provider consent URL

Builds and returns, as a string, the OAuth 2.0 consent URL of one external provider - the address a client opens in a browser so that the user can grant this portal access to their account. The provider's client id, secret and redirect URI have to be saved for the portal first with POST api/2.0/settings/authservice; without them the URL has no client_id and the provider refuses it. Any signed-in portal user may call it, and the call is read-only and safe to repeat. The URL carries response_type=code, the portal's client_id, the provider's redirect_uri, the scope the portal needs (Drive with offline access for Google, signature for DocuSign) and a state pointing back at this portal's thirdparty/{provider}/code page, where the code arrives in the URL fragment as #code=..., or #error/... when the user declines. Only Google 1, Dropbox 2, Docusign 3, Box 4, OneDrive 5, Wordpress 10 and Github 13 produce a URL; any other value is answered with 200 and no URL instead of an error. With desktop=true, the whole query string is copied into state and comes back on the callback. The code is not exchanged here: pass it on as token to POST api/2.0/files/thirdparty to connect the account.

Parameters

Name	In	Type	Description	Notes
provider	path	LoginProvider	The provider whose consent screen is wanted. Only Google, Dropbox, Docusign, Box, OneDrive, Wordpress and Github produce a URL; any other provider is answered with 200 and no URL rather than an error. The provider credentials have to be saved with `POST api/2.0/settings/authservice` first, or the URL comes back without a client identifier and the provider refuses it.	[required] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`]

Responses

Status code	Description	Type	Response headers
200	The consent URL of the provider, ready to be opened in a browser; empty when the requested provider is not one of the seven this operation supports	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
400	Bad Request.	ErrorApiResponse	-
502	Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-
503	Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON.	-	-

Return type