Introduction
This page describes the rest http api. It provides interfaces for administrative purposes and is therefore not intended to be used by clients for endusers. Basic authentication is used to authenticate the client, which needs to be configured in the middleware via the following properties:
com.openexchange.rest.services.basic-auth.login
com.openexchange.rest.services.basic-auth.password
Authentication
basicAuth
HTTP Basic Authentication.
| Security scheme type: | http |
| HTTP Authorization Scheme: | basic |
contextAdminAuth
The API can be accessed via HTTP Basic Auth with context administrator credentials or reseller/master administrator credentials if MASTER_ACCOUNT_OVERRIDE is enabled.
| Security scheme type: | http |
| HTTP Authorization Scheme: | basic |
masterAdminAuth
The API can be accessed via HTTP Basic Auth with master administrator credentials.
| Security scheme type: | http |
| HTTP Authorization Scheme: | basic |
OX REST API
Documentation of the Open-Xchange REST API.
Results
Test-
Admin
Interface for provisioning and other administrative operations.-
Security:
This security scheme must be used:Name Scopes masterAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type global (empty) Close sessions cluster-wide. Default: true
query boolean Body:
Description:A JSON object containing an array of context ids.
Content-type: application/json-
CloseSessionsByContextBody
{- contextIds ( array[integer] ): Array of context IDs
Responses:
200:
A JSON object containing all identifiers of the successfully closed sessions.
Content-type: application/json-
CloseSessionsData
{- closed ( array[string] ): Array of the closed session identifiers
400:
Bad request, response contains error message.
401:
Not authorized
403:
Forbidden
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Security:
This security scheme must be used:Name Scopes masterAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type global (empty) Close sessions cluster-wide. Default: true
query boolean Body:
Description:A JSON object containing an array of session ids.
Content-type: application/json-
CloseSessionsByIdBody
{- sessionIds ( array[string] ): Array of session IDs
Responses:
200:
OK
400:
Bad request, response contains error message.
401:
Not authorized
403:
Forbidden
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Security:
This security scheme must be used:Name Scopes masterAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type global (empty) Close sessions cluster-wide. Default: true
query boolean Body:
Description:A JSON object containing an array of user and context id tuples.
Content-type: application/json-
CloseSessionByUserBody
{- users ( array[object] ): Array of context/user id tuples
Responses:
200:
OK
400:
Bad request, response contains error message.
401:
Not authorized
403:
Forbidden
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Security:
This security scheme must be used:Name Scopes masterAdminAuth
Body:
Description:Information that are needed to pre-assemble the contexts.
Content-type: application/json-
Unknown
{- schema ( string , required ): No description available
- number ( integer , required ): No description available
- filestore_id ( integer ): No description available
Responses:
200:
An array of ids for the pre-assembled contexts.
Content-type: application/json-
PreAssemblyResponse
{- contextIds ( array[integer] ): Array of context IDs that got pre-assembled
- errors ( array[object] ): Optional array of errors that have occurred
400:
Bad request. Invalid or missing information send. Response contains error message.
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
503:
Service Unavailable, e. g. if disabled per configuration.
-
-
Security:
This security scheme must be used:Name Scopes contextAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer Responses:
200:
An array of multifactor devices.
Content-type: application/json-
MultifactorDeviceData
{- id ( string ): The ID of the device
- name ( string ): The name of the device
- providerName ( string ): The name of the device's provider
- enabled ( boolean ): true, if the device is enabled, false if disabled
- backup ( boolean ): true, if the device is a backup device, false otherwise
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
-
Security:
This security scheme must be used:Name Scopes contextAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer Responses:
200:
All devices deleted
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
Security:
This security scheme must be used:Name Scopes contextAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer provider-name (empty) The name of the provider to delete the device for
path string device-id (empty) The ID of the device to delete
path string Responses:
200:
If the device was deleted
401:
Not authorized
404:
Not found. If path is wrong, or if the given provider, or device was not found.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
Security:
This security scheme must be used:Name Scopes contextAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer Responses:
200:
A single login information object.
Content-type: application/json-
LoginInformation
{- enforceMfa ( boolean ): boolean if mfa is enforced or not
- loginCounter ( int ): Counter for succesfull logins of the user
- firstLogin ( string ): Timestamp of the users first login
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
-
Security:
This security scheme must be used:Name Scopes contextAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer Responses:
200:
Multifactor Enforcement informations are reset
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons. Response contains error message.
-
Security:
This security scheme must be used:Name Scopes contextAdminAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-id (empty) The context the user is in
path integer user-id (empty) The ID representing the user
path integer limit (empty) Limits the output to a specific number of entries.
query integer sort (empty) Comma sperated list of fields to sort the output for. Field names that begin with "-" will be sorted descending else the fields get sorted ascending. Valid fields are 'date' and 'client_id'.
query string Responses:
200:
An array of password change entries.
Content-type: application/json-
PasswordChangeHistoryEntry
{- date ( integer , required ): Timestamp (milliseconds since 1970-01-01 00:00:00.000) of the change.
- client_id ( string , required ): Identifier of the client that was used to change the password. For example 'open-xchange-appsuite', 'provisioning-api'.
- client_address ( string ): IP address of the client that was used to change the password. Only contained if it could be determined during the change.
- client_name ( string ): Human-readable name of the client that was used to change the password. Only contained if the client ID has a known human-readable representation. If not set the client should fall-back to 'client_id'.
400:
Bad request, response contains error message.
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer logger (empty) The name of the logger
path string Responses:
200:
The log level of the specified logger
Content-type: application/json-
LogLevel - The log level
401:
Not authorized
404:
In case the context or the logger doesn't exist.
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer logger (empty) The name of the logger
path string Body:
Description:The log level for the given logger
Content-type: application/json-
LogLevel - The log level
Responses:
200:
The log level of a specified logger
Content-type: application/json-
LogLevel - The log level
400:
In case the client sends an invalid body.
401:
Not authorized
404:
In case no logger with the given name exists
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer logger (empty) The name of the logger
path string Responses:
200:
The logger was successfully removed.
401:
Not authorized
404:
In case the no logger with the given name exists for the given context
500:
Internal server error that might have multiple reasons.
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer Responses:
200:
An array of loggers.
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
404:
In case no logger is configured for the given context id.
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer Body:
Description:The loggers
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
Responses:
200:
The changed loggers of this context
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
400:
In case the client sends an invalid body.
401:
Not authorized
404:
In case the context doesn't exist.
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer Responses:
200:
The logger was successfully removed.
401:
Not authorized
404:
In case the no logger with the given name exists for the given session
500:
Internal server error that might have multiple reasons.
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer logger (empty) The name of the logger
path string Responses:
200:
The log level of a specified logger
Content-type: application/json-
LogLevel - The log level
401:
Not authorized
404:
In case no logger with the given name exists or the context or the user doesn't exist
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer logger (empty) The name of the logger
path string Body:
Description:The log level for the given logger
Content-type: application/json-
LogLevel - The log level
Responses:
200:
The log level of a specified logger
Content-type: application/json-
LogLevel - The log level
400:
In case the client sends an invalid body.
401:
Not authorized
404:
In case the context or the user doesn't exist
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer logger (empty) The name of the logger
path string Responses:
200:
The loggers were successfully removed.
401:
Not authorized
404:
In case the context, user or logger doesn't exist
500:
Internal server error that might have multiple reasons.
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer Responses:
200:
An array of existing loggers.
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
404:
In case no logger is configured for the given context and user or if the context or user doesn't exist.
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer Body:
Description:The loggers
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
Responses:
200:
The log level of a specified logger
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
400:
In case the client sends an invalid body.
401:
Not authorized
404:
If the context or user doesn't exist
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer Responses:
200:
The loggers were successfully removed.
401:
Not authorized
404:
In case the context or user doesn't exist
500:
Internal server error that might have multiple reasons.
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer Responses:
200:
Successful operation
Content-type: application/json-
Unknown - true, if the stacktrace is included for the given user, false otherwise
401:
Not authorized
404:
In case the context or the user doesn't exist
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer Body:
Description:Updates if a stacktrace should be included in a HTTP JSON error response to the given user.
Content-type: application/json-
Unknown - true, if the stacktrace should be included for the given user, false otherwise
Responses:
200:
Successful operation
400:
In case the client sends an invalid body.
401:
Not authorized
404:
In case the context or the user doesn't exist
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer Responses:
200:
An array of users and their loggers.
Content-type: application/json-
UsersLoggers
{- userId ( string ): The user id
- loggers ( array[Logger] ): All loggers related to the user
-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Responses:
200:
An array of contexts and their loggers.
Content-type: application/json-
ContextLoggers
{- contextId ( string ): The context id
- loggers ( array[Logger] ): All loggers related to the context
-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type sessionId (empty) The session id
path string logger (empty) The name of the logger
path string Responses:
200:
The log level of a specified logger
Content-type: application/json-
LogLevel - The log level
401:
Not authorized
404:
In case the no logger with the given name exists for the given session
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type sessionId (empty) The session id
path string logger (empty) The name of the logger
path string Body:
Description:The log level for the given logger
Content-type: application/json-
LogLevel - The log level
Responses:
200:
The log level of the set logger
Content-type: application/json-
LogLevel - The log level
400:
In case the client sends an invalid body.
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type sessionId (empty) The session id
path string logger (empty) The name of the logger
path string Responses:
200:
The logger was successfully removed.
401:
Not authorized
404:
In case the no logger with the given name exists for the given session
500:
Internal server error that might have multiple reasons.
-
Parameters:
Parameter Value Description Parameter Type Data Type sessionId (empty) The session id
path string Responses:
200:
An array of loggers.
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
404:
In case no logger is configured for the given session id.
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type sessionId (empty) The session id
path string Body:
Description:The loggers to set
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
Responses:
200:
The set loggers
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
400:
In case the client sends an invalid body.
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type sessionId (empty) The session id
path string Responses:
200:
All loggers were successfully removed.
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
Responses:
200:
An array of sessions and their loggers.
Content-type: application/json-
SessionLoggers
{- sessionId ( string ): The session id
- loggers ( array[Logger] ): All loggers related to the session
-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Responses:
200:
An array of suppressed exception categories.
Content-type: application/json-
ExceptionCategory - The exception category
{
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Body:
Description:The log level for the given logger
Content-type: application/json-
ExceptionCategory - The exception category
{
Responses:
200:
The suppress exception categories
Content-type: application/json-
ExceptionCategory - The exception category
{
400:
In case the client sends an invalid body.
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
DELETE /admin/v1/logconf/suppressed/exception-categories Removes all suppressed exception categories
Responses:
200:
The categories were successfully removed.
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
Parameters:
Parameter Value Description Parameter Type Data Type logger (empty) The name of the logger
path string Responses:
200:
The log level of a specified logger
Content-type: application/json-
LogLevel - The log level
401:
Not authorized
404:
In case no logger with the given name exists
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type logger (empty) The name of the logger
path string Body:
Description:The log level to set
Content-type: application/json-
LogLevel - The log level
Responses:
200:
The log level
Content-type: application/json-
LogLevel - The log level
400:
In case the client sends an invalid body.
401:
Not authorized
404:
In case no logger with the given name exists
500:
Internal server error that might have multiple reasons.
-
-
Responses:
200:
An array of existing loggers.
Content-type: application/json-
Logger
{- name ( string , required ): The name of the logger
-
level
(
LogLevel
,
required
, possibleValues:
OFFERRORWARNINFODEBUGTRACEALL
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
path integer userId (empty) The user id
path integer client (empty) The name of the client to filter
query string Responses:
200:
The last login timestamps of the user
Content-type: application/json-
LastLoginTimestamps
{- timestamps ( array[LastLoginTimestamp] ): The last login timestamps per client
-
LastLoginTimestamp
{- client ( string ): The name of the client
- timestamp ( integer ): The last login time in (in milliseconds since 1970-01-01 00:00:00 UTC)
401:
Not authorized
404:
Not found, if path is wrong (unknown context or user).
500:
Internal server error that might have multiple reasons.
-
-
Parameters:
Parameter Value Description Parameter Type Data Type startDate (empty) The start date in milliseconds since 1970-01-01 00:00:00 UTC
query long endDate (empty) The end date in milliseconds since 1970-01-01 00:00:00 UTC
query long aggregate (empty) If set to true only the total number of logins without duplicate counts (caused by multiple clients per user) is returned.
query string Responses:
200:
The login counts for the given time span.
Content-type: application/json-
LoginCounts
{- sum ( integer ): The sum of all logins
- clients ( array[LoginCount] ): Login counts per clients
-
LoginCount
{- client ( string ): The name of the client
- count ( integer ): The login count of the client
401:
Not authorized
500:
Internal server error that might have multiple reasons.
-
-
Security:
This security scheme must be used:Name Scopes masterAdminAuth
Body:
Description:Notify about site changes
Content-type: application/json-
SiteAvailabilityUpdates
{- previousAvailabilities ( array[object] , required ): Previous availabilities of sites.
- newAvailabilities ( array[object] , required ): New availabilities of sites.
Responses:
200:
Indicating relevant site changes were submitted and locally applied.
304:
Indicating irrelevant site changes were submitted and no action was performed.
400:
Bad request. Invalid or missing information send. Response contains error message.
401:
Not authorized
404:
Not found. If path is wrong. Response contains error message.
409:
Conflict. Site change is already or has just been handled.
500:
Internal server error that might have multiple reasons. Response contains error message.
503:
Service Unavailable, e. g. if disabled per configuration.
-
-
-
Advertisement
The advertisement module-
Parameters:
Parameter Value Description Parameter Type Data Type name (empty) The user's login name
query string contextId (empty) The context id
query long Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
Unknown
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Parameters:
Parameter Value Description Parameter Type Data Type name (empty) The user's login name
query string contextId (empty) The context id
query long Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
PUT /advertisement/v1/config/package Sets an advertisement configuration for a package of a reseller
Parameters:
Parameter Value Description Parameter Type Data Type reseller (empty) The reseller name
query string package (empty) The package name
query string Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
Unknown
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
DELETE /advertisement/v1/config/package Remove the current configuration for a package of a reseller
Parameters:
Parameter Value Description Parameter Type Data Type reseller (empty) The reseller name
query string package (empty) The package name
query string Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
Parameters:
Parameter Value Description Parameter Type Data Type reseller (empty) The reseller's name
query string Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
Unknown
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
query long userId (empty) The user id
query long Body:
Description:JSONObject describing the advertisement configuration
Content-type: application/json-
Unknown
Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id
query long userId (empty) The user id
query long Responses:
200:
The configuration result
400:
Bad request, response contains error message.
401:
Not authorized
-
-
DAVx5
DAVx5 Select configuration endpoint for initial setup and customization re-queries.-
This endpoint serves DAVx5 Select configuration JSON. It supports two modes:
Initial setup (no Authorization header): Redeems a one-time token, creates an app-specific password, and returns the full configuration including DAV URLs, credentials, and UI customization. The user identity is derived from the session reservation bound to the token. The onboarding flow generates a
davx5://setup?config=https://<host>/davx5/v1/config/<token>link; the DAVx5 client extracts the HTTPS URL from theconfigquery parameter and calls this endpoint.Authenticated re-query (Basic Auth header): Returns customization-only JSON with
Cache-ControlandETagheaders for efficient polling. The user identity is derived from the authenticated credentials. The token path segment is ignored in this mode.Parameters:
Parameter Value Description Parameter Type Data Type token (empty) The one-time configuration token obtained from the onboarding flow.
path string Responses:
200:
The DAVx5 configuration. Without an Authorization header, the full configuration including credentials is returned. With Basic Auth, only customization data is returned.
Content-type: application/json-
DAVx5ConfigResponse - DAVx5 configuration response. The shape depends on the request mode: - **Initial setup** (token-based, no Authorization header): All fields are returned. - **Re-query** (Basic Auth): Only `customization` and `supportInfos` are returned.
{- baseRoot ( string ): The DAV base URL. Only present in initial setup responses.
- caldavRoot ( string ): The CalDAV root URL. Only present in initial setup responses.
- carddavRoot ( string ): The CardDAV root URL. Only present in initial setup responses.
- basicAuth ( DAVx5BasicAuth ): The app-specific password credentials for DAV access.
- customization ( DAVx5Customization ): UI customization data for DAVx5 Select.
- supportInfos ( DAVx5SupportInfos ): Support information for DAVx5 Select.
-
DAVx5BasicAuth - The app-specific password credentials for DAV access.
{- username ( string ): The login name for Basic Auth.
- password ( string ): The app-specific password for Basic Auth.
-
DAVx5Customization - UI customization data for DAVx5 Select.
{- productName ( string ): Product name shown in DAVx5 Select.
- description ( string ): Product description shown in DAVx5 Select.
- logoImage ( string ): Logo image as data URI (PNG recommended, 512x512 px, max 256 KB encoded) or HTTPS URL. Note that HTTPS URLs are fetched directly by the client device.
- headerImage ( string ): Header/banner image as data URI (PNG recommended, 1024x256 px, max 256 KB encoded) or HTTPS URL. Note that HTTPS URLs are fetched directly by the client device.
-
DAVx5SupportInfos - Support information for DAVx5 Select.
{- linkDestination ( string ): Support link destination URL.
- linkTitle ( string ): Support link title.
- description ( string ): Support description text.
304:
Not Modified. Returned when the `If-None-Match` header matches the current ETag (re-query mode only).
401:
Unauthorized. The Basic Auth credentials are invalid (re-query mode only).
Content-type: application/json-
DAVx5ErrorResponse - Error response from the DAVx5 configuration endpoint.
{- error ( string ): The error message.
403:
Forbidden. The token is invalid, expired, or has already been used.
Content-type: application/json-
DAVx5ErrorResponse - Error response from the DAVx5 configuration endpoint.
{- error ( string ): The error message.
429:
Too many requests. Rate limit exceeded.
Content-type: application/json-
DAVx5ErrorResponse - Error response from the DAVx5 configuration endpoint.
{- error ( string ): The error message.
500:
Internal server error.
Content-type: application/json-
DAVx5ErrorResponse - Error response from the DAVx5 configuration endpoint.
{- error ( string ): The error message.
503:
Service unavailable. The authentication service is temporarily unavailable.
Content-type: application/json-
DAVx5ErrorResponse - Error response from the DAVx5 configuration endpoint.
{- error ( string ): The error message.
Examples:
Example1: Initial setup (token-based, no auth)GET https://example.com/davx5/v1/config/abc123tokenExample2: Authenticated re-query (Basic Auth)GET https://example.com/davx5/v1/config/abc123token -H "Authorization: Basic dXNlcjpwYXNz" -
-
-
Health
The health-check module-
Responses:
200:
A JSON object containing health data
Content-type: application/json-
HealthData
{-
status
(
string
, possibleValues:
UPDOWN
- checks ( array[HealthCheckData] ): No description available
- service ( ServiceData ): No description available
- blacklist ( array[string] ): Blacklisted health checks
- ignorelist ( array[string] ): Ignored health checks
-
status
(
string
, possibleValues:
-
HealthCheckData
{- name ( string ): The health-check's name
-
status
(
string
, possibleValues:
UPDOWN
- data ( data ): JSON object containing health-check's additional data
-
ServiceData
{- name ( string ): The name
- version ( string ): The middleware version running on this node
- buildDate ( string ): The build date of the middleware running on this node
- date ( string ): The date the health-check was executed
- timeZone ( string ): The node's default time zone
- locale ( string ): The node's default locale
- charset ( string ): The node's default charset
401:
Not authorized
500:
In case of "DOWN"-result or internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Get health statusGET http://localhost:8009/health -
-
-
InternetFreeBusy
Servlet for requesting free busy data.-
Parameters:
Parameter Value Description Parameter Type Data Type contextId (empty) The context id of the context in which the requested user is located.
query integer userName (empty) The name of the user. Typically the local part of the email address.
query string server (empty) The name of the server. Typically the domain part of the email address.
query string weeksIntoPast (empty) The requested time range into the past in weeks. If this value is greater than the configured maximum, the free busy times are only requested to configured maximum. Default value is 1 week into the past.
query integer weeksIntoFuture (empty) The requested time range into the future in weeks. If this value is greater than the configured maximum, the free busy times are only requested to configured maximum. Default value is 4 week into the past.
query integer simple (empty) true, if the VFREEBUSY data should not contain free busy type and free information, false otherwise. Default value is false.
query boolean Responses:
200:
An iCalendar text containing the requested free busy data.
Content-type: text/calendar-
Unknown
400:
In case one parameter is invalid.
404:
In case the servlet is not enabled, if no existing user with the requested user name, server and context id is found or if this user has not published his free busy data.
500:
In case an internal server error occurs.
-
-
-
Metrics
The metrics module-
Responses:
200:
The metrics in the prometheus format.
Content-type: text/plain-
Unknown
401:
Not authorized
403:
In case basic authentication is enabled and an external client tries to access this resouce without using ssl.
-
-
-
Preliminary
This module contains preliminary endpoints which can change in the future.-
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The context id
path long user (empty) The user id
path long Responses:
200:
A JSON array containing the capabilities for the user
Content-type: application/json
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Get capabilitiesGET http://localhost:8009/preliminary/capabilities/v1/all/1/3 -
-
Looks up the free/busy periods of one or more users of a context within a certain time range, administratively, i.e. without acting on behalf of a session user. In contrast to the client-facing free/busy request of the HTTP API, the response is reduced to the pure free/busy periods - the events behind a busy period are never disclosed, not even in their anonymized form. This makes the endpoint suitable for services that only need to know when a user is busy, like a booking service performing a calendar conflict check. The configured free/busy visibility of the queried users is honored, i.e. users that restricted their free/busy data to their own context or hid it entirely are reported with a warning and without any free/busy periods.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context the queried users belong to
path integer attendees (empty) The users to query the free/busy data for, each one referenced either by its numerical internal user identifier or by one of its email addresses (including aliases). May be supplied as comma-separated list, by repeating the parameter, or by any combination of both. Resources and rooms can be queried alongside the users by passing their email address.
query array from (empty) The start of the requested time range, either as UTC timestamp in milliseconds, as ISO-8601 date or date/time, or in the iCalendar format also used by the HTTP API. Values without an explicit timezone or UTC indicator are interpreted as UTC.
query string until (empty) The end of the requested time range, in the same notation as 'from'. Must be after 'from'.
query string merge (empty) 'true' to merge any overlapping free/busy periods of a user into the most conflicting busy times, 'false' to get one period per underlying appointment. Defaults to 'true'.
query boolean Responses:
200:
A JSON array holding one free/busy result per requested user, in the order the users were requested in.
Content-type: application/json-
FreeBusyResult - The free/busy data of a single queried calendar user.
{- attendee ( FreeBusyAttendee ): The calendar user the free/busy data was queried for. Reported as resolved, i.e. an internal entity carries its identifier, common name and mail address no matter how it was referenced in the request.
- freeBusyTime ( array[FreeBusyPeriod] ): The free/busy periods of the calendar user within the requested time range. Absent if no free/busy data could be served for the calendar user, in which case a warning is present instead.
- warnings ( array[FreeBusyWarning] ): Warnings concerning the calendar user, if any.
-
FreeBusyAttendee - The calendar user the free/busy data was queried for. Reported as resolved, i.e. an internal entity carries its identifier, common name and mail address no matter how it was referenced in the request.
{- entity ( integer ): The numerical internal identifier of the calendar user, only set if it could be resolved.
-
cuType
(
string
, possibleValues:
INDIVIDUALGROUPRESOURCEROOMUNKNOWN
- uri ( string ): The calendar user address URI, usually a "mailto:"-URI.
- cn ( string ): The common name of the calendar user.
- email ( string ): The mail address of the calendar user.
-
FreeBusyPeriod - A single free/busy period. The event behind the period is intentionally not disclosed.
{- startTime ( integer ): The start of the period, as UTC timestamp in milliseconds.
- endTime ( integer ): The end of the period, as UTC timestamp in milliseconds.
- fbType ( string ): The type of the period, as defined in RFC 5545, section 3.2.9. Typically "BUSY", "BUSY-TENTATIVE", "BUSY-UNAVAILABLE" or "FREE".
-
FreeBusyWarning - A warning concerning a queried calendar user, e.g. if it could not be resolved, or if it restricted the visibility of its free/busy data.
{- error ( string ): The translated error message.
- error_params ( array[string] ): The message parameters.
- error_id ( string ): Unique error identifier to help finding this error instance in the server logs.
- error_desc ( string ): The technical error message (always English) useful for debugging the problem.
- error_stack ( array[string] ): The stack trace of the associated Java exception, only present if com.openexchange.ajax.response.includeStackTraceOnError is enabled.
- version ( string ): The version of the middleware node that produced the warning.
- code ( string ): Error code consisting of an upper-case module identifier and a four- or five-digit message number, separated by a dash; e.g. "CAL-40312".
- categories ( string ): The upper-case category identifier the error belongs to.
- category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.
400:
A parameter is missing, or a user identifier or time range boundary could not be parsed.
401:
Not authorized
404:
The referenced context does not exist.
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Query the free/busy data of a user referenced by identifier and another one referenced by email addressGET http://localhost:8009/preliminary/chronos/v1/freebusy/1?attendees=3,jane.doe@example.com&from=2026-07-28T00:00:00Z&until=2026-08-04T00:00:00Z -
-
Looks up the free/busy periods of a single user of a context within a certain time range, administratively, i.e. without acting on behalf of a session user. This is the convenience variant of the batch endpoint for the common case of a single queried user, yielding the free/busy result directly instead of wrapping it into an array. Since the user is referenced through a path segment here, only its numerical internal user identifier is accepted - use the batch endpoint to reference a user by its email address. As with the batch endpoint, the response is reduced to the pure free/busy periods and the configured free/busy visibility of the queried user is honored.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context the queried user belongs to
path integer user (empty) The identifier of the user to query the free/busy data for
path integer from (empty) The start of the requested time range, either as UTC timestamp in milliseconds, as ISO-8601 date or date/time, or in the iCalendar format also used by the HTTP API. Values without an explicit timezone or UTC indicator are interpreted as UTC.
query string until (empty) The end of the requested time range, in the same notation as 'from'. Must be after 'from'.
query string merge (empty) 'true' to merge any overlapping free/busy periods into the most conflicting busy times, 'false' to get one period per underlying appointment. Defaults to 'true'.
query boolean Responses:
200:
A JSON object holding the free/busy result of the user.
Content-type: application/json-
FreeBusyResult - The free/busy data of a single queried calendar user.
{- attendee ( FreeBusyAttendee ): The calendar user the free/busy data was queried for. Reported as resolved, i.e. an internal entity carries its identifier, common name and mail address no matter how it was referenced in the request.
- freeBusyTime ( array[FreeBusyPeriod] ): The free/busy periods of the calendar user within the requested time range. Absent if no free/busy data could be served for the calendar user, in which case a warning is present instead.
- warnings ( array[FreeBusyWarning] ): Warnings concerning the calendar user, if any.
-
FreeBusyAttendee - The calendar user the free/busy data was queried for. Reported as resolved, i.e. an internal entity carries its identifier, common name and mail address no matter how it was referenced in the request.
{- entity ( integer ): The numerical internal identifier of the calendar user, only set if it could be resolved.
-
cuType
(
string
, possibleValues:
INDIVIDUALGROUPRESOURCEROOMUNKNOWN
- uri ( string ): The calendar user address URI, usually a "mailto:"-URI.
- cn ( string ): The common name of the calendar user.
- email ( string ): The mail address of the calendar user.
-
FreeBusyPeriod - A single free/busy period. The event behind the period is intentionally not disclosed.
{- startTime ( integer ): The start of the period, as UTC timestamp in milliseconds.
- endTime ( integer ): The end of the period, as UTC timestamp in milliseconds.
- fbType ( string ): The type of the period, as defined in RFC 5545, section 3.2.9. Typically "BUSY", "BUSY-TENTATIVE", "BUSY-UNAVAILABLE" or "FREE".
-
FreeBusyWarning - A warning concerning a queried calendar user, e.g. if it could not be resolved, or if it restricted the visibility of its free/busy data.
{- error ( string ): The translated error message.
- error_params ( array[string] ): The message parameters.
- error_id ( string ): Unique error identifier to help finding this error instance in the server logs.
- error_desc ( string ): The technical error message (always English) useful for debugging the problem.
- error_stack ( array[string] ): The stack trace of the associated Java exception, only present if com.openexchange.ajax.response.includeStackTraceOnError is enabled.
- version ( string ): The version of the middleware node that produced the warning.
- code ( string ): Error code consisting of an upper-case module identifier and a four- or five-digit message number, separated by a dash; e.g. "CAL-40312".
- categories ( string ): The upper-case category identifier the error belongs to.
- category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.
400:
A parameter is missing, or a time range boundary could not be parsed.
401:
Not authorized
404:
The referenced context or user does not exist.
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Query the free/busy data of a single userGET http://localhost:8009/preliminary/chronos/v1/freebusy/1/3?from=2026-07-28T00:00:00Z&until=2026-08-04T00:00:00Z -
-
Lists, for every principal entity in the context that holds at least one cross-context liaison, the foreign sharing contexts the entity has liaisons with, broken down per groupware module. The liaison registry is consulted directly for the context's liaisons rather than by enumerating users, so only entities that effectively hold a liaison appear. Each entry is reported under its own entity identifier and tagged as a user or group, the kind being probed dynamically. Trust zones are included for user entities only.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context.
path integer Responses:
200:
A JSON object listing the cross-context liaisons of the liaison-holding entities in the context.
Content-type: application/json-
Unknown
{- context ( integer ): The context identifier.
- entities ( array[object] ): One entry per principal entity in the context that holds at least one cross-context liaison.
401:
Missing or invalid HTTP Basic authentication credentials (administrative endpoint).
404:
The context does not exist.
500:
In case of an internal server error that might have multiple reasons.
Examples:
Example: List the cross-context access received by all entities in a contextGET http://localhost:8009/preliminary/crosscontext/v1/inbound/1337 -
-
Lists the foreign sharing contexts the user has cross-context liaisons with, broken down per groupware module, together with the trust zones configured for the user. Liaisons granted to one of the user's groups are folded into the result implicitly, i.e. direct (to the user entity) and indirect (via group membership) liaisons are combined.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context the user belongs to.
path integer user (empty) The identifier of the user.
path integer Responses:
200:
A JSON object describing the user's cross-context liaisons and trust zones.
Content-type: application/json-
Unknown
{- context ( integer ): The context identifier.
- user ( integer ): The user identifier.
- trustZones ( array[string] ): The trust zone tags configured for the user.
- liaisons ( liaisons ): The established liaisons, as a mapping of groupware module name to the list of foreign sharing context identifiers. Only modules with at least one liaison are included.
401:
Missing or invalid HTTP Basic authentication credentials (administrative endpoint).
404:
The context or user does not exist.
500:
In case of an internal server error that might have multiple reasons.
Examples:
Example: List the cross-context access a user receivedGET http://localhost:8009/preliminary/crosscontext/v1/inbound/1337/3 -
-
Retracts the cross-context access the principal received: for each of its liaisons whose type has a registered retractor, removes the live backing access (e.g. a mail folder ACL via doveadm) and drops the liaison row. The optional
from,ownerandmodulequery parameters scope the purge. The operation is an unconditional operator override - it does not consult the trust-zone authority - and is lenient: each liaison is handled in isolation, an already-absent access is a no-op, a retractor that cannot complete (e.g. its backend is unavailable) leaves that row for a later retry, and a liaison whose type has no registered retractor is left untouched and reported underskippedNoRetractor.Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context the principal belongs to.
path integer user (empty) The identifier of the principal (user) whose received access to retract.
path integer from (empty) Optional filter - only retract liaisons received from this sharing (owner) context.
query integer owner (empty) Optional filter - only retract liaisons whose owning entity within the sharing context matches (relevant for mail folder shares; owner-agnostic liaisons carry 0).
query integer module (empty) Optional filter - only retract liaisons of this groupware module (e.g. mail, calendar).
query string Responses:
200:
A JSON object summarizing the purge outcome.
Content-type: application/json-
Unknown
{- context ( integer ): The context identifier.
- user ( integer ): The principal identifier.
- retracted ( integer ): The number of liaisons whose backing access was retracted and whose row was dropped.
- deferred ( integer ): The number of liaisons left in place because their retractor could not complete (e.g. the backend was unavailable); a later run retries them.
- failed ( integer ): The number of liaisons that errored during retraction and were kept.
- skippedNoRetractor ( skippedNoRetractor ): Per liaison type, the count of liaisons left untouched because no retractor is registered for that type (row and access both kept). Absent when none were skipped.
401:
Missing or invalid HTTP Basic authentication credentials (administrative endpoint).
404:
The context or user does not exist.
500:
In case of an internal server error that might have multiple reasons.
Examples:
Example: Retract all cross-context access a user receivedDELETE http://localhost:8009/preliminary/crosscontext/v1/inbound/1337/3 -
-
Lists the cross-context shares the user has granted out - the foreign access that exists on the folders it owns, its mailbox, and the deputies it appointed - read owner-locally from each backing store (no cross-schema fan-out). Resource-owner-scoped: it reports the foreign access on the user's resources, not necessarily "what the user personally granted", as the backing stores record no granted-by attribution.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the owner's context.
path integer user (empty) The identifier of the owner user whose granted-out access to list.
path integer Responses:
200:
A JSON object listing the user's outbound cross-context shares.
Content-type: application/json-
Unknown
{- context ( integer ): The owner context identifier.
- user ( integer ): The owner user identifier.
- shares ( array[object] ): One entry per cross-context share granted out from the user's resources.
401:
Missing or invalid HTTP Basic authentication credentials (administrative endpoint).
404:
The context or user does not exist.
500:
In case of an internal server error that might have multiple reasons.
Examples:
Example: List the cross-context access a user granted outGET http://localhost:8009/preliminary/crosscontext/v1/outbound/1337/3 -
-
Retracts the cross-context access the user has granted out from its own resources: removes the foreign access on the user's folders / mailbox and revokes the deputies it appointed, cleaning up the corresponding grantee-side liaison rows. The optional
to(a grantee context) andmodulequery parameters scope the purge. The operation is an unconditional operator override - it does not consult the trust-zone authority - and is lenient and per-share isolated; deputy shares are revoked first so their cascade onto the projected folder/mail shares runs before those are touched.Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the owner's context.
path integer user (empty) The identifier of the owner user whose granted-out access to retract.
path integer to (empty) Optional filter - only retract shares granted to this grantee context.
query integer module (empty) Optional filter - only retract shares of this groupware module (e.g. mail, calendar).
query string Responses:
200:
A JSON object summarizing the purge outcome.
Content-type: application/json-
Unknown
{- context ( integer ): The owner context identifier.
- user ( integer ): The owner user identifier.
- retracted ( integer ): The number of shares whose backing access was retracted.
- deferred ( integer ): The number of shares left in place because their backing could not be reached (e.g. the backend was unavailable); a later run retries them.
- failed ( integer ): The number of shares that errored during retraction and were kept.
401:
Missing or invalid HTTP Basic authentication credentials (administrative endpoint).
404:
The context or user does not exist.
500:
In case of an internal server error that might have multiple reasons.
Examples:
Example: Retract all cross-context access a user granted outDELETE http://localhost:8009/preliminary/crosscontext/v1/outbound/1337/3 -
-
Body:
Description:JSONObject containing the push message
Content-type: application/json-
PushMessage
{-
event
(
string
, possibleValues:
messageNew
-
user
(
string
):
The user identifier in the format
@ . E.g. 3@1 - folder ( string ): The folder id
- imap-uid ( string ): The mail uid
- from ( string ): The from header of the mail
- subject ( string ): The subject of the mail
- unseen ( integer ): The number of unseen mails
- snippet ( string ): A mail teaser
-
event
(
string
, possibleValues:
Responses:
200:
A JSON object with a success field set to 'true'.
Content-type: application/json-
SuccessResponse
{- success ( boolean ): No description available
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
-
-
Cluster-internal endpoint consumed exclusively by the JMAP-IMAP proxy. The endpoint is gated by two independent authentication layers:
Service layer — HTTP Basic-Auth against the cluster-internal REST credentials (com.openexchange.rest.services.basic-auth.login/.password) identifies the caller as the JMAP-IMAP proxy.
User layer — the proxy must forward the value of the user'sopen-xchange-secret-<hash>cookie via theX-OX-Session-Secretheader. The Middleware compares it against the session's stored secret so that a service holding only the cluster-internal credentials cannot resolve arbitrary session identifiers.
The session is resolved in a touch-free manner; repeated polling does not reset the session's idle expiration counter.Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type session (empty) The Middleware session identifier.
path string X-OX-Session-Secret (empty) The plain value of the user's
open-xchange-secret-<hash>cookie, forwarded by the proxy from the originating client request.header string Responses:
200:
Validation succeeded. The response body holds the IMAP backend coordinates plus the credentials the proxy must use.
Content-type: application/json-
MailValidateSessionResponse
{- identity ( identity , required ): The session-owning user's basic identifying information.
- imap ( imap , required ): Connection coordinates of the user's primary IMAP backend.
- auth ( auth , required ): The authentication credentials the proxy must use against the IMAP backend.
- session ( session , required ): Session-level lifetime information.
-
identity - The session-owning user's basic identifying information.
{- user ( string , required ): The numeric user identifier, encoded as a decimal string.
- context ( string , required ): The numeric context identifier, encoded as a decimal string.
- displayName ( string ): The user's display name; `null` if not configured.
- primaryEmail ( string ): The user's primary email address (falls back to the primary mail account's primary address).
-
imap - Connection coordinates of the user's primary IMAP backend.
{- host ( string , required ): The IMAP backend host name.
- port ( integer , required ): The IMAP backend TCP port.
- secure ( boolean , required ): `true` for implicit TLS (typically port 993), `false` for plain or STARTTLS-upgraded connections.
-
auth - The authentication credentials the proxy must use against the IMAP backend.
{-
type
(
string
,
required
, possibleValues:
LOGINXOAUTH2OAUTHBEARER
- loginName ( string , required ): The login name the IMAP backend expects.
- secret ( string , required ): The plaintext password (for `LOGIN`) or the OAuth2 access token (for `XOAUTH2` / `OAUTHBEARER`). Empty string when the Middleware itself uses an empty secret (e.g. guest sessions).
- secretExpiresInSeconds ( integer ): Remaining lifetime of the secret in whole seconds. `null` for `LOGIN` (static password). For OAuth-based types this is the lesser of the token's remaining TTL and the session's remaining lifetime; clients should re-fetch before reaching `0`.
-
type
(
string
,
required
, possibleValues:
-
session - Session-level lifetime information.
{- expiresInSeconds ( integer , required ): Estimated remaining session lifetime in whole seconds, derived from the configured `sessionDefaultLifeTime` / `sessionLongLifeTime` and the session's `stay-signed-in` flag. Floored at `0`; intended as an upper bound for the proxy's validation cache TTL, not as a hard expiry indicator.
401:
Either the HTTP Basic-Auth credentials are missing/invalid, the session is unknown/expired, or the
X-OX-Session-Secretheader is missing or mismatches the session's stored secret. The response body is the standard OX error JSON with codeSES-0203so the proxy can forward it unchanged to the originating client.403:
The user has no primary mail account configured or the primary account is disabled. The response body is the standard OX error JSON with code
MAIL-0114. -
-
Parameters:
Parameter Value Description Parameter Type Data Type session (empty) The session id
path string Responses:
200:
A JSON object containing informations about the session.
Content-type: application/json-
Unknown - A json object containing informations about the session.
{- context ( integer ): The context id.
- user ( integer ): The user id.
- guest ( boolean ): Whether the session belongs to a guest user or not.
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Resolve sessionGET http://localhost:8009/preliminary/session/v1/get/1234567890 -
-
Gets the dynamically evaluated effective permissions and capabilities a user has for a specific shared account. Instead of their explicit internal identifiers, both the user and the shared account are referenced either by their email address (resolved through the registered mail resolver service) or by their mail login string (resolved through the registered mail login resolver service). For both the user and the shared account, exactly one of the respective two query parameters must be supplied.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type userEmail (empty) The email address of the user. Mutually exclusive with 'userMailLogin'.
query string userMailLogin (empty) The mail login string of the user. Mutually exclusive with 'userEmail'.
query string accountEmail (empty) The email address of the shared account. Mutually exclusive with 'accountMailLogin'.
query string accountMailLogin (empty) The mail login string of the shared account. Mutually exclusive with 'accountEmail'.
query string Responses:
200:
A JSON object holding the effective shared account information.
Content-type: application/json-
SharedAccount - The effective access a user has for a shared account, including the dynamically evaluated permissions and capabilities.
{- accountId ( string ): The identifier of the shared account, in the format [user-id]@[context-id].
- entityInfo ( entityInfo ): Basic information about the entity behind the shared account.
- capabilities ( array[string] ): The effective capabilities the user has for the shared account.
- moduleConfigurations ( moduleConfigurations ): The effective module-specific configuration, keyed by module identifier (e.g. "mail" or "calendar").
-
entityInfo - Basic information about the entity behind the shared account.
{- identifier ( string ): The identifier of the shared account entity.
- type ( string ): The type of the entity, e.g. "user".
- display_name ( string ): The display name of the entity.
- entity ( integer ): The numerical user identifier of the entity, only set if the entity resides in the same context as the requested user.
- contact ( contact ): Additional contact data of the entity.
-
contact - Additional contact data of the entity.
{- title ( string ): No description available
- first_name ( string ): No description available
- last_name ( string ): No description available
- email1 ( string ): No description available
- image1_url ( string ): No description available
400:
A user or shared account identifier was missing, or both identifiers were supplied at once.
401:
Not authorized
404:
The supplied email address or mail login could not be resolved, or the user has no access to the requested shared account.
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
503:
The mail resolver service or mail login resolver required for resolving is not available.
Examples:
Example: Get the effective access of a user for a shared account, both referenced by email addressGET http://localhost:8009/preliminary/sharedaccounts/v1/account?userEmail=jane.doe@example.com&accountEmail=team@example.com -
-
Lists all shared accounts a user is able to access, along with the dynamically evaluated effective permissions and capabilities for each of them. Instead of his explicit internal identifiers, the user is referenced either by his email address (resolved through the registered mail resolver service) or by his mail login string (resolved through the registered mail login resolver service). Exactly one of the two query parameters must be supplied.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type userEmail (empty) The email address of the user. Mutually exclusive with 'userMailLogin'.
query string userMailLogin (empty) The mail login string of the user. Mutually exclusive with 'userEmail'.
query string Responses:
200:
A JSON array holding the effective shared account information.
Content-type: application/json-
SharedAccount - The effective access a user has for a shared account, including the dynamically evaluated permissions and capabilities.
{- accountId ( string ): The identifier of the shared account, in the format [user-id]@[context-id].
- entityInfo ( entityInfo ): Basic information about the entity behind the shared account.
- capabilities ( array[string] ): The effective capabilities the user has for the shared account.
- moduleConfigurations ( moduleConfigurations ): The effective module-specific configuration, keyed by module identifier (e.g. "mail" or "calendar").
-
entityInfo - Basic information about the entity behind the shared account.
{- identifier ( string ): The identifier of the shared account entity.
- type ( string ): The type of the entity, e.g. "user".
- display_name ( string ): The display name of the entity.
- entity ( integer ): The numerical user identifier of the entity, only set if the entity resides in the same context as the requested user.
- contact ( contact ): Additional contact data of the entity.
-
contact - Additional contact data of the entity.
{- title ( string ): No description available
- first_name ( string ): No description available
- last_name ( string ): No description available
- email1 ( string ): No description available
- image1_url ( string ): No description available
400:
No user identifier was supplied, or both identifiers were supplied at once.
401:
Not authorized
404:
The supplied email address or mail login could not be resolved to a user.
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
503:
The mail resolver service or mail login resolver required for resolving is not available.
Examples:
Example: List the shared accounts accessible by a user referenced by email addressGET http://localhost:8009/preliminary/sharedaccounts/v1/accounts?userEmail=jane.doe@example.com -
-
Lists all shared accounts a user is able to access, along with the dynamically evaluated effective permissions and capabilities for each of them. The user is referenced by his explicit internal identifiers.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context the user belongs to
path long user (empty) The identifier of the user to evaluate the accessible shared accounts for
path long Responses:
200:
A JSON array holding the effective shared account information.
Content-type: application/json-
SharedAccount - The effective access a user has for a shared account, including the dynamically evaluated permissions and capabilities.
{- accountId ( string ): The identifier of the shared account, in the format [user-id]@[context-id].
- entityInfo ( entityInfo ): Basic information about the entity behind the shared account.
- capabilities ( array[string] ): The effective capabilities the user has for the shared account.
- moduleConfigurations ( moduleConfigurations ): The effective module-specific configuration, keyed by module identifier (e.g. "mail" or "calendar").
-
entityInfo - Basic information about the entity behind the shared account.
{- identifier ( string ): The identifier of the shared account entity.
- type ( string ): The type of the entity, e.g. "user".
- display_name ( string ): The display name of the entity.
- entity ( integer ): The numerical user identifier of the entity, only set if the entity resides in the same context as the requested user.
- contact ( contact ): Additional contact data of the entity.
-
contact - Additional contact data of the entity.
{- title ( string ): No description available
- first_name ( string ): No description available
- last_name ( string ): No description available
- email1 ( string ): No description available
- image1_url ( string ): No description available
401:
Not authorized
404:
The referenced context or user does not exist.
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: List the shared accounts accessible by a userGET http://localhost:8009/preliminary/sharedaccounts/v1/1/3 -
-
Gets the dynamically evaluated effective permissions and capabilities a user has for a specific shared account. Both the user and the shared account are referenced by their explicit internal identifiers.
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context (empty) The identifier of the context the user belongs to
path long user (empty) The identifier of the user to evaluate the shared account access for
path long accountId (empty) The identifier of the shared account, in the format [user-id]@[context-id].
path string Responses:
200:
A JSON object holding the effective shared account information.
Content-type: application/json-
SharedAccount - The effective access a user has for a shared account, including the dynamically evaluated permissions and capabilities.
{- accountId ( string ): The identifier of the shared account, in the format [user-id]@[context-id].
- entityInfo ( entityInfo ): Basic information about the entity behind the shared account.
- capabilities ( array[string] ): The effective capabilities the user has for the shared account.
- moduleConfigurations ( moduleConfigurations ): The effective module-specific configuration, keyed by module identifier (e.g. "mail" or "calendar").
-
entityInfo - Basic information about the entity behind the shared account.
{- identifier ( string ): The identifier of the shared account entity.
- type ( string ): The type of the entity, e.g. "user".
- display_name ( string ): The display name of the entity.
- entity ( integer ): The numerical user identifier of the entity, only set if the entity resides in the same context as the requested user.
- contact ( contact ): Additional contact data of the entity.
-
contact - Additional contact data of the entity.
{- title ( string ): No description available
- first_name ( string ): No description available
- last_name ( string ): No description available
- email1 ( string ): No description available
- image1_url ( string ): No description available
400:
The supplied shared account identifier is malformed.
401:
Not authorized
404:
The referenced context or user does not exist, or the user has no access to the requested shared account.
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Get the effective access of a user for a specific shared accountGET http://localhost:8009/preliminary/sharedaccounts/v1/1/3/5@1 -
-
Parameters:
Parameter Value Description Parameter Type Data Type mail* (empty) The mail addresses as a semicolon separated list
path string Responses:
200:
A json object containg subobjects for every mail address which contains the user id, context id and addtional informations.
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Examples:
Example: Resolve addressesGET http://localhost:8009//preliminary/utilities/mailResolver/v1/resolve/anton@context1.ox.test;berta@context1.ox.test
-
-
Push
The push module-
Body:
Description:JSONObject containing the push mail
Content-type: application/json-
PushMail
{-
event
(
string
, possibleValues:
messageNew
-
user
(
string
):
The user identifier in the format
@ , @ or the user's mail login. - folder ( string ): The folder id
- body ( string ): The RFC822 Mail body
-
event
(
string
, possibleValues:
Responses:
200:
Empty repsonse.
401:
Not authorized
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
-
-
-
Request-Analysis
This module contains endpoints used to analyze requests-
Analyzes the request data and maps it to a marker if possible
Security:
This security scheme must be used:Name Scopes basicAuth
Body:
Description:A json object describing the request
Content-type: application/json-
RequestData
{- method ( string , required ): The method of the request
- url ( string , required ): The url of the request
- remoteIP ( string , required ): the remote ip of the request
- headers ( array[object] , required ): An array of headers of the request
- body ( string ): The body of the request as a base64 encoded string
Responses:
200:
Successful operation
Content-type: application/json-
AnalysisResult - An analysis result
{- marker ( string , required ): No description available
- headers ( headers ): An object containing headers which should be added to the request
- type ( string ): No description available
-
headers - An object containing headers which should be added to the request
{- x-ox-context-id ( integer , required ): No description available
- x-ox-user-id ( integer ): No description available
- x-ox-login ( string ): No description available
400:
In case a required field is missing
404:
Returned in case no marker could be found for the given request
422:
The body is required to determine the marker for the given request
500:
In case of internal server error that might have multiple reasons. Response contains error message.
Content-type: application/json-
Unknown
-
-
-
Userfeedback
The user feedback module-
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to send.
path string start (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is sent. If not set, all feedback up to -e is sent.
query long end (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is sent. If not set, all feedback since -s is sent.
query long delimiter (empty) The column delimiter used. Default: ';'
query string Responses:
200:
Export data into a CSV file
Content-type: application/octet-stream-
Unknown
400:
Bad request, response contains error message.
Content-type: application/octet-stream-
Unknown
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: application/octet-stream-
Unknown
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: application/octet-stream-
Unknown
Examples:
Example: Export user feedback from 2016-01-01 to 2016-12-31 as CSVGET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1?start=1451606400&end=1483228799 -
-
Security:
This security scheme must be used:Name Scopes basicAuth
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to send.
path string start (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is sent. If not set, all feedback up to -e is sent.
query long end (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is sent. If not set, all feedback since -s is sent.
query long Responses:
200:
A JSON array containing the stored user feedbacks.
Content-type: application/json-
Unknown
400:
Bad request, response contains error message.
Content-type: application/json-
Unknown
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: application/json-
Unknown
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Export user feedback from 2016-01-01 to 2016-12-31GET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1/raw?start=1451606400&end=1483228799 -
-
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to send.
path string start (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is sent. If not set, all feedback up to -e is sent.
query long end (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is sent. If not set, all feedback since -s is sent.
query long Body:
Description:JSONObject with fields "subject" for custom mail subject, "body" for custom mail body, boolean "compress" to compress the mail attachment and "recipients" (an JSON Array containing address, display name and PGP key (if available) for every recipient).
Content-type: application/json-
Unknown
{
Responses:
200:
Info message about sent status
Content-type: */*-
Unknown
400:
Bad request, response contains error message.
Content-type: */*-
Unknown
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: */*-
Unknown
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: */*-
Unknown
Examples:
Example: Export user feedback from 2016-01-01 to 2016-12-31 and send it via mail to user1@example.org and user2@example.orgPOST http://localhost:8009/userfeedback/v1/send/default/star-rating-v1?start=1451606400&end=1483228799 {"subject":"User Feedback", "body":"User Feedback", "compress":true, "recipients": [ {"address":"user1@example.org", "displayName":"User 1", "pgp_key":"-----BEGIN PGP PUBLIC KEY BLOCK-----\r\nVersion: BCPG v1.56...."}, {"address":"user2@example.org", "displayName":"User 2", "pgp_key":"-----BEGIN PGP PUBLIC KEY BLOCK-----\r\nVersion: BCPG v1.56...."} ] } -
-
Parameters:
Parameter Value Description Parameter Type Data Type context-group (empty) The context group identifying the global DB where the feedback is stored.
path string type (empty) The feedback type to delete.
path string start (empty) Start time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given after this time is deleted. If not set, all feedback up to -e is deleted.
query long end (empty) End time in milliseconds since 1970-01-01 00:00:00 UTC. Only feedback given before this time is deleted. If not set, all feedback since -s is deleted.
query long Responses:
200:
Info message when successfull.
Content-type: application/json-
Unknown
400:
Bad request, response contains error message.
Content-type: application/json-
Unknown
401:
Not authorized
404:
Not found, if path is wrong (unknown context group or feedback type). Response contains error message.
Content-type: application/json-
Unknown
500:
Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.
Content-type: application/json-
Unknown
Examples:
Example: Delete user feedback from 2016-01-01 to 2016-12-31DELETE http://localhost:8009/userfeedback/v1/default/star-rating-v1?start=1451606400&end=1483228799 -
-