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.

AccountRecovery

Unauthenticated user-initiated password recovery flow (request, reset, password requirements). Legacy alias paths are kept for backward compatibility and marked deprecated.

POST /account-recovery/request Initiates a password recovery (legacy path).
Legacy-shape entry point preserved for existing clients that were built against the standalone account-recovery service. New integrations should use POST /account-recovery/v1/forgot-password instead.

Behaves identically to the modern endpoint but accepts an additional optional app field that is stamped onto the issued token's metadata. Core reads no brand header; with cloud-plugins both endpoints take the brand from the header named by com.openexchange.cloudplugins.header (default Host).

Body:
Description:

No description available

Content-type: application/json

LegacyRecoveryRequestBody Composed Schema
ALLOF: RecoveryForgotPasswordRequest Object Body of the legacy `POST /account-recovery/request` endpoint.

RecoveryForgotPasswordRequest
{

email ( string , required ): The email address to initiate recovery for. Treated as the recovery email — the lookup is performed against the user-attribute key that stores the user's verified recovery address.

}

Unknown
{

app ( string ): Optional application identifier passed by the calling client (e.g. `mail`, `calendar`). Stored opaquely on the issued token; consumed at reset time by deployment-specific URL resolvers to redirect the user back to the originating application.

}
Responses:
204:

Acknowledgement. Response shape is constant regardless of whether the address matched any account.

GET /account-recovery/requirements Returns the password policy (legacy path).

Legacy-shape password-requirements endpoint preserved for existing clients. Identical response shape to GET /account-recovery/v1/password-requirements; new integrations should use that path instead.

Parameters:

Parameter	Value	Description	Parameter Type	Data Type
token	(empty)	The reset token from the recovery link. With a live token the policy of that user is returned; an absent, unknown or expired token returns the server-wide policy.	query	string

Responses:

200:

The policy.

Content-type: application/json

RecoveryPasswordRequirements - The admin-flow password policy that a new password must satisfy. Returned by the `password-requirements` endpoint so client UIs can pre-validate the password locally before submission. Defaults are no enforcement (`minLength=0`, all flags `false`); operators opt in via `com.openexchange.passwordchange.admin.*` properties.
{
- minLength ( integer , required ): Minimum allowed password length. `0` disables the check.
- specialCharRequired ( boolean , required ): Whether the password must contain at least one non-alphanumeric character.
- digitRequired ( boolean , required ): Whether the password must contain at least one digit (`0`–`9`).
- lowerCaseRequired ( boolean , required ): Whether the password must contain at least one lowercase letter (`a`–`z`).
- upperCaseRequired ( boolean , required ): Whether the password must contain at least one uppercase letter (`A`–`Z`).
}

503:

The configuration service is unavailable.

POST /account-recovery/reset Completes a password reset (legacy path).
Legacy-shape reset endpoint preserved for existing clients. Behaves like POST /account-recovery/v1/reset plus an optional app field in the body that can override the value captured at request time when resolving the post-reset loginUrl. The success response contains a loginUrl when a deployment-specific resolver produced one, otherwise 204 No Content.

Body:
Description:

No description available

Content-type: application/json

LegacyRecoveryResetRequest Composed Schema
ALLOF: RecoveryResetRequest Object Body of the legacy `POST /account-recovery/reset` endpoint. Adds the optional `app` field on top of the modern `ResetRequest` shape so deployment-specific URL resolvers can produce an app-aware `loginUrl` in the response.

RecoveryResetRequest
{

token ( string , required ): The single-use reset token previously delivered to the user. Consumed atomically on a successful POST.

password ( string , required ): The new password. Validated against the admin-flow password policy (`AdminPasswordChangeProperties`); a violation fails the request.

}

Unknown
{

app ( string ): Optional application identifier overriding any value captured at request time. Used by deployment-specific resolvers to compute the post-reset `loginUrl`.

}
Responses:
200:

The password has been changed; a deployment-specific login URL is included for the client to redirect to.

Content-type: application/json

LegacyRecoveryResetResponse - Body of a successful legacy `POST /account-recovery/reset`. Returned only when a deployment-specific URL resolver produces a login URL for the consumed token. When no login URL is configured the response is `204 No Content` instead, with no body.
{

loginUrl ( string ): Absolute URL the client should redirect the user to after the reset completes.

}
204:

The password has been changed; no login URL is configured for the consumed token.
400:

Missing `token` or `password`, an unknown/expired token, or another input-validation failure.
403:

Recovery is not permitted for the bound user; the change was refused.
503:

A required service is currently unavailable.
POST /account-recovery/v1/forgot-password Initiates a password recovery for the supplied address.
Looks up users whose stored recovery email, primary address or alias matches the supplied address and, for each match that is not blacklisted, not rate-limited, and below the per-user cap on concurrent outstanding tokens, issues a single-use reset token and dispatches the configured notification (mail and/or SMS) asynchronously.

The response shape is identical regardless of whether the address matched any account, preventing recovery from being used to enumerate registered addresses.

Body:
Description:

No description available

Content-type: application/json

RecoveryForgotPasswordRequest
{

email ( string , required ): The email address to initiate recovery for. Treated as the recovery email — the lookup is performed against the user-attribute key that stores the user's verified recovery address.

}
Responses:
200:

Acknowledgement message.

Content-type: application/json

RecoveryForgotPasswordResponse
{

message ( string ): A generic acknowledgement message returned regardless of whether the submitted address matched any account. The message is deliberately constant to avoid leaking which addresses are registered.

}
400:

The request body is not valid JSON.
415:

The request has a `Content-Type` other than JSON.
Examples:

Example1: Initiate recovery
POST /account-recovery/v1/forgot-password Content-Type: application/json {"email": "user@example.com"}

GET /account-recovery/v1/password-requirements Returns the password policy a recovery reset must satisfy.

Returns the admin-flow password policy so a recovery reset UI can pre-validate the password locally before submission. The endpoint is anonymous. With the reset token it reports the policy of the token's user, as the reset enforces it; without one it reports the server-wide policy, which per-context or per-user overrides may tighten at submit time.

Parameters:

Parameter	Value	Description	Parameter Type	Data Type
token	(empty)	The reset token from the recovery link. With a live token the policy of that user is returned; an absent, unknown or expired token returns the server-wide policy.	query	string

Responses:

200:

The policy.

Content-type: application/json

RecoveryPasswordRequirements - The admin-flow password policy that a new password must satisfy. Returned by the `password-requirements` endpoint so client UIs can pre-validate the password locally before submission. Defaults are no enforcement (`minLength=0`, all flags `false`); operators opt in via `com.openexchange.passwordchange.admin.*` properties.
{
- minLength ( integer , required ): Minimum allowed password length. `0` disables the check.
- specialCharRequired ( boolean , required ): Whether the password must contain at least one non-alphanumeric character.
- digitRequired ( boolean , required ): Whether the password must contain at least one digit (`0`–`9`).
- lowerCaseRequired ( boolean , required ): Whether the password must contain at least one lowercase letter (`a`–`z`).
- upperCaseRequired ( boolean , required ): Whether the password must contain at least one uppercase letter (`A`–`Z`).
}

503:

The configuration service is unavailable.

GET /account-recovery/v1/reset Checks that a reset token is still valid.

Validity check used by the reset UI on page-load. The token is NOT consumed; a subsequent POST can still successfully consume the same token. The response names the account in masked form, so the page MUST NOT take the address from its own URL. Returns 400 if the token query parameter is missing or blank and 410 if the token is unknown, expired, already used, or was not issued for a password reset.

Parameters:

Parameter	Value	Description	Parameter Type	Data Type
token	(empty)	The reset token previously delivered to the user.	query	string

Responses:

200:

The token is valid and can be submitted.

Content-type: application/json

RecoveryResetTokenValidation
{
- ready ( boolean ): Always `true` when the response status is `200`. The endpoint only confirms that a token was supplied; it does not consume the token, so an actual reset can still proceed.
- email ( string ): The primary email address of the account the token resets, masked to its first character and domain. Absent when the address cannot be read; the reset page then shows a generic text.
}

400:

The `token` query parameter is missing or blank.

403:

Account recovery is switched off for the token's user; the token stays valid.

410:

The token is unknown, has expired, was already used, is not a reset token, or its user no longer exists.

500:

An unexpected error occurred while looking up the token.

503:

The token service is currently unavailable.

POST /account-recovery/v1/reset Completes a password reset using a previously-issued token.
Performs an admin-initiated password change for the user bound to the supplied reset token and consumes the token once the change succeeded. A refused password or a failing password-change backend leaves the token valid for a retry. Side effects include invalidating cached user state, killing the user's existing sessions, and dispatching the reset-confirmation notification asynchronously across the configured channels.

Body:
Description:

No description available

Content-type: application/json

RecoveryResetRequest
{

token ( string , required ): The single-use reset token previously delivered to the user. Consumed atomically on a successful POST.

password ( string , required ): The new password. Validated against the admin-flow password policy (`AdminPasswordChangeProperties`); a violation fails the request.

}
Responses:
200:

The password has been changed.

Content-type: application/json

RecoveryResetResponse
{

success ( boolean ): Always `true` when the response status is `200`. Indicates the password has been persisted.

}
400:

Missing `token` or `password` in the request body, or the password was refused by the password policy or the password-change backend. A refusal carries a JSON body with the OX error `code` and a human-readable `error`; the token stays valid.

Content-type: application/json

Unknown
{

code ( string ): The OX error code, e.g. `USR-0101`.

error ( string ): The reason in English, suitable for display.

}
403:

Recovery is not permitted for the bound user; the change was refused.
410:

The token is unknown, has already been consumed, or has expired.
500:

An unexpected error occurred during the change.
503:

A required service is unavailable, no password-change backend is enabled for the user, or the backend failed. The token stays valid.
POST /account-recovery/v1/verify-email Verifies a recovery email address using a time-limited token.
Consumes the single-use verification token that was dispatched to the user's recovery email address after it was stored. On success the address is marked as verified in the user record.

Returns 409 if the recovery email address stored for the user has changed since the token was issued (stale token). Returns 410 if the token is unknown, has already been consumed, or has expired.

Body:
Description:

No description available

Content-type: application/json

RecoveryVerifyEmailRequest
{

token ( string , required ): The single-use verification token previously delivered to the user's recovery email address. Consumed atomically on success.

}
Responses:
200:

The recovery email address has been verified.

Content-type: application/json

RecoveryVerifyEmailResponse
{

success ( boolean ): Always `true` when the response status is `200`. Indicates the recovery email address has been marked as verified.

}
400:

Missing or blank `token` in the request body.
409:

The recovery email address has changed since the token was issued.
410:

The token is unknown, has already been consumed, or has expired.
503:

A required service is currently unavailable.

GET /account-recovery/waypoint Redirects the user to the deployment-specific reset UI.

AccountRecoveryAdmin

Admin REST endpoints for managing stored recovery details and admin-initiated password resets. Basic Auth required.

GET /admin/v1/account-recovery/details/email/{email} Returns the recovery details stored for the user identified by email.

Resolves the supplied email to a single (contextId, userId) via the RecoveryUserResolver chain, then returns the user's stored recovery details. Fields the user has not set are omitted from the response.

Security:

This security scheme must be used:

Name	Scopes
basicAuth

Parameters:

Parameter	Value	Description	Parameter Type	Data Type
email	(empty)	The recovery email address identifying the target user.	path	email
x-component	(empty)	Free-form identifier of the calling component. Logged for traceability; does not affect behaviour.	header	string

Responses:

200:

The recovery details.

Content-type: application/json

RecoveryDetails - The user's stored recovery contact data. Each field is independently optional and absent from the response when not set on the user. Used both by the AJAX module and by the admin REST endpoints.
{
- phone ( string ): Recovery phone number. Accepted in international format with a leading `+` (e.g. `+49 170 1234567`) and returned in E.164 (e.g. `+491701234567`).
- email ( string ): Recovery email address, a bare address with a dotted domain; display-name forms are rejected.
- pin ( string ): Recovery PIN, a shared secret a support agent can ask the user for. Absent when not set.
}

400:

Missing or empty `email` path segment.

401:

Authentication failed.

404:

No user matches the supplied email.

429:

Per-caller rate limit exceeded.

500:

An unexpected error occurred during resolution.

503:

A required service is currently unavailable.

PUT /admin/v1/account-recovery/details/email/{email} Updates recovery details for the user identified by email.

Updates the recovery fields supplied in the JSON body. An omitted field leaves the stored value unchanged; a field that is empty or null clears it; any other value sets it. The post-update state is returned.

Security:

This security scheme must be used:

Name	Scopes
basicAuth

Parameters:

Parameter	Value	Description	Parameter Type	Data Type
email	(empty)	The recovery email address identifying the target user.	path	email
x-component	(empty)	Free-form identifier of the calling component. Logged for traceability; does not affect behaviour.	header	string

Body:

Description:

No description available

Content-type: application/json

RecoveryAdminDetailsUpdate - Recovery fields to update. An omitted field leaves the stored value unchanged; an empty string or `null` clears it; any other value sets it.
{
- phone ( string ): New recovery phone number.
- recoveryEmail ( string ): New recovery email address, a bare address with a dotted domain; display-name forms are rejected.
- pin ( string ): New recovery PIN, a shared secret a support agent can ask the user for. No whitespace, 1 to 64 characters.
}

Responses:

200:

The updated recovery details.

Content-type: application/json

RecoveryDetails - The user's stored recovery contact data. Each field is independently optional and absent from the response when not set on the user. Used both by the AJAX module and by the admin REST endpoints.
{
- phone ( string ): Recovery phone number. Accepted in international format with a leading `+` (e.g. `+49 170 1234567`) and returned in E.164 (e.g. `+491701234567`).
- email ( string ): Recovery email address, a bare address with a dotted domain; display-name forms are rejected.
- pin ( string ): Recovery PIN, a shared secret a support agent can ask the user for. Absent when not set.
}

400:

Missing or empty `email` path segment, a supplied value that fails validation, or a `phone`, `recoveryEmail` or `pin` query parameter (values MUST travel in the JSON body).

401:

Authentication failed.

404:

No user matches the supplied email.

429:

Per-caller rate limit exceeded.

500:

An unexpected error occurred during the update.

503:

A required service is currently unavailable.

PUT /admin/v1/account-recovery/password/email/{email} Performs an admin-initiated password change for the user identified by email.

Resolves the supplied email to a single (contextId, userId) and changes that user's password via the highest-ranked AdminPasswordChangeService. When the body carries no password a fresh password is generated and returned in the response so the caller can deliver it out-of-band.

Side effects mirror the public recovery reset: cached user state is invalidated and existing user sessions are killed.

Security:

This security scheme must be used:

Name	Scopes
basicAuth

Parameters:

Parameter	Value	Description	Parameter Type	Data Type
email	(empty)	The recovery email address identifying the target user.	path	email
x-component	(empty)	Free-form identifier of the calling component, logged for traceability.	header	string

Body:

Description:

No description available

Content-type: application/json

RecoveryAdminPasswordUpdate
{
- password ( string ): The new password. When omitted or empty, a random password is generated server-side.
}

Responses:

200:

The password that was set. When the caller supplied a password explicitly this echoes the same value; otherwise it carries the freshly-generated password.

Content-type: application/json

Unknown
{
- password ( string ): The password that is now stored for the user.
}

400:

Missing or empty `email` path segment, or a `password` query parameter (the password MUST travel in the JSON body).

401:

Authentication failed.

404:

No user matches the supplied email.

429:

Per-caller rate limit exceeded.

500:

An unexpected error occurred during the change.

503:

A required service is currently unavailable.

Admin

Interface for provisioning and other administrative operations.

POST /admin/v1/close-sessions/by-context Close all sessions belonging to a context

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.

POST /admin/v1/close-sessions/by-id Close a session by its ID

POST /admin/v1/close-sessions/by-user Close all sessions belonging to a user

POST /admin/v1/contexts/pre-assemble Creates pre-assembled (disabled) contexts.
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.

GET /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/devices Lists all multifactor authentication devices for a user.

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.

DELETE /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/devices Deletes all multifactor authentication devices for a user.

DELETE /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/devices/{provider-name}/{device-id} Deletes a multifactor authentication device.

GET /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/enforcement Resets the multifactor enforcement informations for an user.

DELETE /admin/v1/contexts/{context-id}/users/{user-id}/multifactor/enforcement Resets the multifactor enforcement informations for an user.

GET /admin/v1/contexts/{context-id}/users/{user-id}/passwd-changes Lists the history of password changes for a user.

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.

GET /admin/v1/logconf/context/{contextId}/logger/{logger} Gets the log level of a logger for a given context

PUT /admin/v1/logconf/context/{contextId}/logger/{logger} Sets the log level of a logger for a given context

DELETE /admin/v1/logconf/context/{contextId}/logger/{logger} Removes a logger for a given context

GET /admin/v1/logconf/context/{contextId}/loggers Gets all loggers for a given context

PUT /admin/v1/logconf/context/{contextId}/loggers Sets the loggers for a given context

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:
  - OFF
  - ERROR
  - WARN
  - INFO
  - DEBUG
  - TRACE
  - ALL
  ): The log level
}

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:
  - OFF
  - ERROR
  - WARN
  - INFO
  - DEBUG
  - TRACE
  - ALL
  ): The log level
}

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.

DELETE /admin/v1/logconf/context/{contextId}/loggers Removes all loggers for a given context

GET /admin/v1/logconf/context/{contextId}/user/{userId}/logger/{logger} Gets the log level of a logger for a given user

PUT /admin/v1/logconf/context/{contextId}/user/{userId}/logger/{logger} Sets the log level of a logger for a given user

DELETE /admin/v1/logconf/context/{contextId}/user/{userId}/logger/{logger} Removes a logger for a given user

GET /admin/v1/logconf/context/{contextId}/user/{userId}/loggers Gets all loggers for a given user

PUT /admin/v1/logconf/context/{contextId}/user/{userId}/loggers Sets the loggers for a given user

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:
  - OFF
  - ERROR
  - WARN
  - INFO
  - DEBUG
  - TRACE
  - ALL
  ): The log level
}

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:
  - OFF
  - ERROR
  - WARN
  - INFO
  - DEBUG
  - TRACE
  - ALL
  ): The log level
}

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.

DELETE /admin/v1/logconf/context/{contextId}/user/{userId}/loggers Removes all loggers for a given user

GET /admin/v1/logconf/context/{contextId}/user/{userId}/stacktrace/include-on-error Gets if a stacktrace is included in a HTTP JSON error response to the given user.

PUT /admin/v1/logconf/context/{contextId}/user/{userId}/stacktrace/include-on-error Sets if a stacktrace should be included in a HTTP JSON error response to the given user.

GET /admin/v1/logconf/context/{contextId}/users Gets all user-based loggers within the context

GET /admin/v1/logconf/contexts/ Gets all context-based loggers
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:

OFF

ERROR

WARN

INFO

DEBUG

TRACE

ALL

): The log level

}
401:

Not authorized
500:

Internal server error that might have multiple reasons.

GET /admin/v1/logconf/session/{sessionId}/logger/{logger} Gets the log level of a specific logger for a given session

PUT /admin/v1/logconf/session/{sessionId}/logger/{logger} Sets the log level of a logger for a given session

DELETE /admin/v1/logconf/session/{sessionId}/logger/{logger} Removes a logger for a given session

GET /admin/v1/logconf/session/{sessionId}/loggers Gets all loggers for a given session

PUT /admin/v1/logconf/session/{sessionId}/loggers Sets all loggers for a given session

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:
  - OFF
  - ERROR
  - WARN
  - INFO
  - DEBUG
  - TRACE
  - ALL
  ): The log level
}

Responses:

200:

The set loggers

Content-type: application/json

Logger
{
- name ( string , required ): The name of the logger
- level ( LogLevel , required , possibleValues:
  - OFF
  - ERROR
  - WARN
  - INFO
  - DEBUG
  - TRACE
  - ALL
  ): The log level
}

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/session/{sessionId}/loggers Removes all loggers for a given session

GET /admin/v1/logconf/sessions/ Gets all session-based loggers
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:

OFF

ERROR

WARN

INFO

DEBUG

TRACE

ALL

): The log level

}
401:

Not authorized
500:

Internal server error that might have multiple reasons.
GET /admin/v1/logconf/suppressed/exception-categories Gets all supressed exception categories
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.
PUT /admin/v1/logconf/suppressed/exception-categories Sets the suppressed exception categories
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.

GET /admin/v1/logconf/system/logger/{logger} Gets the log level of a specific logger

PUT /admin/v1/logconf/system/logger/{logger} Sets the log level of an existing logger

GET /admin/v1/logconf/system/loggers Gets all known loggers
Responses:
200:

An array of existing loggers.

Content-type: application/json

Logger
{

name ( string , required ): The name of the logger

level ( LogLevel , required , possibleValues:

OFF

ERROR

WARN

INFO

DEBUG

TRACE

ALL

): The log level

}
401:

Not authorized
500:

Internal server error that might have multiple reasons.

GET /admin/v1/login/context/{contextId}/user/{userId}/timestamps Retrieves the last login timestamps of a user for each client.

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.

GET /admin/v1/login/counter Gets the amount of logins per client within a given time span

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.

POST /segmenter/v1/changed Notify site changes

The advertisement module

PUT /advertisement/v1/config/name Sets an advertisement configuration for a given user by name

DELETE /advertisement/v1/config/name Remove the current configuration for the user

PUT /advertisement/v1/config/package Sets an advertisement configuration for a package of a reseller

DELETE /advertisement/v1/config/package Remove the current configuration for a package of a reseller

PUT /advertisement/v1/config/reseller Sets all advertisement configurations for a given reseller

PUT /advertisement/v1/config/user Sets an advertisement configuration for a given user by id

DELETE /advertisement/v1/config/user Remove the current configuration for the user identified by userId

Authentication

Endpoints used by external authentication components, e.g. a SAML or OIDC front-end, that own the user's session: resolving user identities, performing logins, multifactor authentication, triggering login handlers and driving the OpenID Connect token and logout lifecycle.

POST /authentication/v1/login Performs a login on behalf of a client

Performs the login denoted by loginAction for the client request that the external authentication component received, and reports the outcome so that the component can establish its own session. The client request is forwarded in the body; the login action reads its parameters, headers and cookies from there just like the classic login servlet reads them from the HTTP request.

Whatever the login action decides, a call that could be answered is answered with status 200, carrying one of three shapes:

ExternalAuthLoginSuccessResponse - the login succeeded, the identity to establish the session for is enclosed
ExternalAuthLoginRedirectResponse - the client is to be sent to redirectUrl instead, e.g. to the login page of a password-protected share
ExternalAuthLoginChallengeResponse - the client is to be asked for credentials with the enclosed challenge

A rejected login attempt is answered with 400 or 403 carrying the error to relay to the client; any other status is to be treated as a server error.

Security:

This security scheme must be used:

Name	Scopes
basicAuth

Parameters:

Parameter Value Description Parameter Type Data Type

loginAction

(empty)

The login action to perform. /authentication/v1/login/methods lists the actions available on the node. The standard ones are:

login - Authenticates the user with login and password (plus optional client, version, authId, language, staySignedIn, ...), like the HTTP API login?action=login.
formlogin - Like login, but strict like the HTTP API login?action=formlogin: client and version are required, and authId unless form login without it is configured. Reports the UI location in redirectUrl, honoring the uiWebPath parameter.
tokenLogin - Authenticates with login, password and the client token clientToken, like the HTTP API login?action=tokenLogin. Reports the server token in tokenLogin.
tokens - Looks up the session created by a previous tokenLogin by its clientToken and serverToken, checking the client IP address given in remoteAddress.
redeemToken - Redeems a login token (parameters token, appId, optional client and authId) obtained via the HTTP API token API.
inFlight - Authenticates the user from the Basic credentials in the forwarded Authorization header with the *dav client, for requests served without an interactive login, e.g. by WebDAV/CalDAV/CardDAV clients.
shareResolve - Resolves the share link given as sharePath (the share token, optionally followed by the target path) to its guest. A password-protected share is either authenticated from forwarded Basic credentials, answered with a challenge (share served in flight) or with a redirect to the share login page. Unknown shares and failures are answered with a redirect to a message page.
anonymous - Logs in the guest of a password-protected anonymous share link with the parameters share (token), target (target path) and password.
guest - Logs in the named guest of a share with the parameters share, target and, for a password-protected guest, password.
resetGuestPassword - The password reset flow of a named guest with parameter share: sends the confirmation mail, asks for the new password once confirm is given, and sets it and logs the guest in once confirm and password are given. The intermediate steps are answered with a redirect.
oidcLogin - Only available if OpenID Connect is enabled: redeems the session reservation token sessionToken handed out at the end of the OpenID Connect flow; uriFragment is used as deep link. Reports the ID token in meta.idToken.

query

string

Body:

Description:

No description available

Content-type: application/json

ExternalAuthLoginBody - The client request the external authentication component received, forwarded to the middleware. The selected login action reads everything it needs from here - most notably from parameters - just like the classic login servlet reads it from the HTTP request.
Unknown fields are rejected. No field is required as such; what a login action needs depends on the action, see loginAction.
{
- server ( ExternalAuthLoginServer ): The server the client addressed with its original request
- remoteAddress ( string ): The IP address of the client
- body ( string ): The raw body of the original request. Currently not evaluated by any login action.
- headers ( headers ): The headers of the original request, keyed by header name, each with the list of its values. Header names are matched case-insensitively.
- parameters ( parameters ): The request parameters of the original request (query and form parameters), keyed by parameter name, each with the list of its values. Where a single value is read, the first one is taken.
- cookies ( array[ExternalAuthLoginCookie] ): The cookies of the original request. If a cookie name occurs more than once, its first value is used.
}
ExternalAuthLoginServer - The server the client addressed with its original request
{
- host ( string ): The host name the client addressed, e.g. appsuite.example.com
- port ( integer ): The port the client addressed, e.g. 443
- scheme ( string ): The scheme the client used. The request is considered secure if it is https (compared case-insensitively).
- path ( path ): The path and query of the original request
}
path - The path and query of the original request
{
- pathInfo ( string ): The path info of the original request
- queryString ( string ): The query string of the original request
}
ExternalAuthLoginCookie - A cookie the client sent along with its original request. Only name and value are evaluated; the other attributes are accepted but ignored.
{
- name ( string ): The cookie name
- value ( string ): The cookie value
- domain ( string ): The cookie domain (ignored)
- path ( string ): The cookie path (ignored)
- secure ( boolean ): The secure flag (ignored)
- httpOnly ( boolean ): The HttpOnly flag (ignored)
- sameSite ( string ): The SameSite attribute (ignored)
- expires ( string ): The expiration date in ISO 8601 format (ignored)
}

Responses:

200:

The outcome of the login, one of ExternalAuthLoginSuccessResponse,
ExternalAuthLoginRedirectResponse or ExternalAuthLoginChallengeResponse

Content-type: application/json

Unknown Composed Schema
ONEOF: ExternalAuthLoginSuccessResponse ExternalAuthLoginRedirectResponse ExternalAuthLoginChallengeResponse
ExternalAuthLoginSuccessResponse - The outcome of a successful login: the identity that has been authenticated, for which the external authentication component establishes its session.
{
- multifactor ( boolean ): true if the user still has to pass a second authentication factor, see /authentication/v1/multifactor. Omitted if no second factor is required.
- scopes ( array[string] , required ): The scopes granted to the session. If the session carries no restricted scopes, this is the single scope * (full access).
- userId ( string , required ): The identifier of the authenticated user
- cid ( string , required ): The identifier of the context the authenticated user belongs to
- schema ( integer , required ): The numeric suffix of the name of the database schema the user's context lives in, e.g. 7 for oxdatabase_7, or 0 if the schema name carries no numeric suffix
- user ( string ): The login name of the authenticated user. For a share guest, this is the guest's e-mail address, or guest for an anonymous guest.
- meta ( meta ): Additional information about the user
- redirectUrl ( string ): Where the client is to be sent after the login, if the login action determines a location
- share ( share ): The share target the login addresses. Only present for the share-related login actions.
- tokenLogin ( tokenLogin ): Only set by the tokenLogin action
}
meta - Additional information about the user
{
- prefLanguage ( string ): The user's preferred language, e.g. en_US
- idToken ( string ): The OpenID Connect ID token of the login, only set by the oidcLogin action
}
share - The share target the login addresses. Only present for the share-related login actions.
{
- username ( string ): The login name of the guest, same as user
- module ( string ): The name of the module of the share target, e.g. infostore
- folder ( string ): The folder identifier of the share target
- item ( string ): The item identifier of the share target, if the share addresses a single item
- inFlight ( boolean ): Only set by the shareResolve action: true if the share is served within the request that asks for it (e.g. by a WebDAV client), so that no session is to be handed to the client; false if a session is to be handed over.
}
tokenLogin - Only set by the tokenLogin action
{
- serverToken ( string ): The server token of the new session, to be combined with the client token
- jsonResponse ( string ): The value of the jsonResponse request parameter, false if absent, i.e. whether the client expects a JSON response rather than a redirect
}
ExternalAuthLoginRedirectResponse - The login did not establish a session, but the client is to be sent to the given location, e.g. to the login page of a password-protected share or to a page displaying a message.
{
- redirectUrl ( string , required ): Where the client is to be sent
}
ExternalAuthLoginChallengeResponse - The login needs credentials the request did not carry. The challenge is to be relayed to the client, e.g. as a WWW-Authenticate header of a 401 response.
{
- challenge ( challenge , required ): No description available
}
challenge
{
- scheme ( string ): The authentication scheme to ask for, e.g. Basic
- realm ( string ): The protection space, e.g. Share/Guest/1/7
}

400:

In case loginAction is missing (MISSING_PARAMETER) or unknown (INVALID_PARAMETER_VALUE), the request body is missing, null, cannot be parsed or carries unknown fields (INVALID_JSON_REQUEST_BODY), or the login attempt is rejected because of the user's input, e.g. invalid credentials or a missing parameter. The body carries the error to relay to the client. A rejected attempt the login action gives no reason for is answered without a body.

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{
- 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 error, if known.
- 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. LGI-0006.
- categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.
- category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.
}

401:

Not authorized

403:

In case the login attempt is rejected because permission is denied, e.g. for a deactivated user or context

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{
- 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 error, if known.
- 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. LGI-0006.
- categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.
- category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.
}

500:

In case of internal server error that might have multiple reasons. The body carries the error if the login action reported one.

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{
- 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 error, if known.
- 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. LGI-0006.
- categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.
- category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.
}

Examples:

Example: Log a user in with login and password

POST http://localhost:8009/authentication/v1/login?loginAction=login
Content-Type: application/json

{"server":{"host":"appsuite.example.com","port":443,"scheme":"https","path":{"pathInfo":"/appsuite/api/login","queryString":"action=login"}},"remoteAddress":"192.0.2.10","headers":{"user-agent":[{"name":"user-agent","value":"Mozilla/5.0"}]},"parameters":{"login":[{"name":"login","value":"john.doe@example.com"}],"password":[{"name":"password","value":"secret"}],"client":[{"name":"client","value":"open-xchange-appsuite"}]},"cookies":[]}

Example: Resolve a share link

POST http://localhost:8009/authentication/v1/login?loginAction=shareResolve
Content-Type: application/json

{"server":{"host":"appsuite.example.com","port":443,"scheme":"https","path":{"pathInfo":"/appsuite/api/share/1a2b3c4d/1/8/MTIz","queryString":""}},"remoteAddress":"192.0.2.10","headers":{},"parameters":{"sharePath":[{"name":"sharePath","value":"1a2b3c4d/1/8/MTIz"}]},"cookies":[]}

POST /authentication/v1/login-handlers Triggers the login handlers for an externally authenticated user
Runs the middleware's login handlers for a user that has just been authenticated by the external authentication component. As the session is owned by that component, the middleware never performs a regular login that would run them, so the component calls this endpoint alongside the request that resolves the token.

The handlers run detached from the call: the response is returned as soon as the user has been resolved, while the handlers keep running. Handlers that must not run asynchronously (non-transient or blocking ones) are left out.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthTriggerLoginHandlersBody - The user the login handlers shall be triggered for, i.e. what the external authentication component has just resolved the access token to. Unknown fields are rejected.
{

contextId ( integer , required ): The identifier of the user's context, must be positive

userId ( integer , required ): The user identifier, must be positive

token ( string , required ): The OAuth access token the identity has been resolved from. The handlers run with a session carrying it, so that they can authenticate against the user's backends on the user's behalf (e.g. the mail server).

client ( string ): The client identifier to report to the login handlers, e.g. open-xchange-appsuite

userAgent ( string ): The user agent to report to the login handlers

remoteAddress ( string ): The IP address the client is coming from

}
Responses:
202:

The login handlers have been triggered
400:

In case the request body is missing, null, cannot be parsed or carries unknown fields (INVALID_JSON_REQUEST_BODY), or does not denote a positive contextId, a positive userId and a token (MISSING_PARAMETER), or another error of category USER_INPUT occurs

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case of an error of category PERMISSION_DENIED

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons, e.g. the user or context cannot be resolved

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Trigger the login handlers
POST http://localhost:8009/authentication/v1/login-handlers Content-Type: application/json {"contextId":1,"userId":3,"token":"eyJhbGciOi...","client":"open-xchange-appsuite","userAgent":"Mozilla/5.0","remoteAddress":"192.0.2.10"}
GET /authentication/v1/login/methods Lists the available login actions
Lists the login actions available on this node, i.e. the values accepted as loginAction by /authentication/v1/login, sorted alphabetically.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Responses:
200:

The names of the available login actions

Content-type: application/json
401:

Not authorized
Examples:

Example: List the available login actions
GET http://localhost:8009/authentication/v1/login/methods ["anonymous","formlogin","guest","inFlight","login","redeemToken","resetGuestPassword","shareResolve","tokenLogin","tokens"]
POST /authentication/v1/multifactor?action=finishAuthentication Finishes the authentication against a multifactor device
Verifies the answer to the challenge of the device denoted by providerName and deviceId of the user denoted by userId and contextId. Lockout handling and listener notifications apply just like for the HTTP API multifactor actions.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthMultifactorBody - The user and, depending on the action, the device a multifactor request refers to. There is no session, so the user is identified solely by userId and contextId. Unknown fields are ignored.
{

userId ( string , required ): The user identifier as a numeric string, e.g. "3"

contextId ( string , required ): The context identifier as a numeric string, e.g. "1"

providerName ( string ): The name of the multifactor provider the device belongs to, e.g. TOTP. Required for startAuthentication and finishAuthentication.

deviceId ( string ): The identifier of the device to authenticate with. Required for startAuthentication and finishAuthentication.

answer ( answer ): The provider-specific answer to the challenge, passed to the provider verbatim. Only evaluated by finishAuthentication; its content is the same as for the corresponding HTTP API multifactor action, e.g. {"secret_code":"123456"} for TOTP.

clientInfo ( clientInfo ): Information about the client that initiated the login. Unknown fields are ignored.

}

clientInfo - Information about the client that initiated the login. Unknown fields are ignored.
{

userAgent ( string ): The user agent of the client (currently not evaluated)

ip ( string ): The IP address of the client (currently not evaluated)

host ( string ): The user-facing host the login is performed against. Required by host-aware providers like WebAuthn/U2F to derive the relying party's origin.

}
Responses:
200:

The authentication succeeded; the body is an empty JSON object

Content-type: application/json

Unknown
{

}
400:

In case the action parameter is missing (MISSING_PARAMETER) or unknown (INVALID_PARAMETER_VALUE), the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), userId or contextId is missing or not numeric (MFA-0013), the provider is unknown (MFA-0006), a provider misses a parameter of the answer (MFA-0013), or another error of category USER_INPUT occurs, e.g. a missing providerName or deviceId, an unknown device or a wrong answer

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case permission is denied, e.g. an invalid authentication factor

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons, e.g. an unknown user

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Answer the challenge of a TOTP device
POST http://localhost:8009/authentication/v1/multifactor?action=finishAuthentication Content-Type: application/json {"userId":"3","contextId":"1","providerName":"TOTP","deviceId":"2f0c8e5a","answer":{"secret_code":"123456"}}
POST /authentication/v1/multifactor?action=list Lists the multifactor devices of a user
Lists the enabled multifactor devices and the available multifactor providers of the user denoted by userId and contextId, for a login at which no session exists yet. Only userId, contextId and clientInfo are evaluated.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthMultifactorBody - The user and, depending on the action, the device a multifactor request refers to. There is no session, so the user is identified solely by userId and contextId. Unknown fields are ignored.
{

userId ( string , required ): The user identifier as a numeric string, e.g. "3"

contextId ( string , required ): The context identifier as a numeric string, e.g. "1"

providerName ( string ): The name of the multifactor provider the device belongs to, e.g. TOTP. Required for startAuthentication and finishAuthentication.

deviceId ( string ): The identifier of the device to authenticate with. Required for startAuthentication and finishAuthentication.

answer ( answer ): The provider-specific answer to the challenge, passed to the provider verbatim. Only evaluated by finishAuthentication; its content is the same as for the corresponding HTTP API multifactor action, e.g. {"secret_code":"123456"} for TOTP.

clientInfo ( clientInfo ): Information about the client that initiated the login. Unknown fields are ignored.

}

clientInfo - Information about the client that initiated the login. Unknown fields are ignored.
{

userAgent ( string ): The user agent of the client (currently not evaluated)

ip ( string ): The IP address of the client (currently not evaluated)

host ( string ): The user-facing host the login is performed against. Required by host-aware providers like WebAuthn/U2F to derive the relying party's origin.

}
Responses:
200:

The devices and providers of the user

Content-type: application/json

ExternalAuthMultifactorListResponse - The user's enabled multifactor devices and the providers available to the user
{

devices ( array[ExternalAuthMultifactorDevice] ): The enabled devices of all available providers

providers ( array[ExternalAuthMultifactorProvider] ): The available providers

}

ExternalAuthMultifactorDevice - An enabled multifactor device of the user
{

id ( string ): The device identifier

providerName ( string ): The name of the provider the device belongs to

name ( string ): The user-friendly device name

backup ( boolean ): Whether the device is a backup device

}

ExternalAuthMultifactorProvider - A multifactor provider available to the user
{

name ( string ): The provider name

backupOnlyProvider ( boolean ): Whether the provider is used only for backing up other providers

}
400:

In case the action parameter is missing (MISSING_PARAMETER) or unknown (INVALID_PARAMETER_VALUE), the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), userId or contextId is missing or not numeric (MFA-0013), the provider is unknown (MFA-0006), a provider misses a parameter of the answer (MFA-0013), or another error of category USER_INPUT occurs, e.g. a missing providerName or deviceId, an unknown device or a wrong answer

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case permission is denied, e.g. an invalid authentication factor

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons, e.g. an unknown user

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: List the devices of a user
POST http://localhost:8009/authentication/v1/multifactor?action=list Content-Type: application/json {"userId":"3","contextId":"1","clientInfo":{"host":"appsuite.example.com"}}
POST /authentication/v1/multifactor?action=startAuthentication Starts the authentication against a multifactor device
Issues the provider-specific challenge for the device denoted by providerName and deviceId of the user denoted by userId and contextId, for a login at which no session exists yet. answer is not evaluated.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthMultifactorBody - The user and, depending on the action, the device a multifactor request refers to. There is no session, so the user is identified solely by userId and contextId. Unknown fields are ignored.
{

userId ( string , required ): The user identifier as a numeric string, e.g. "3"

contextId ( string , required ): The context identifier as a numeric string, e.g. "1"

providerName ( string ): The name of the multifactor provider the device belongs to, e.g. TOTP. Required for startAuthentication and finishAuthentication.

deviceId ( string ): The identifier of the device to authenticate with. Required for startAuthentication and finishAuthentication.

answer ( answer ): The provider-specific answer to the challenge, passed to the provider verbatim. Only evaluated by finishAuthentication; its content is the same as for the corresponding HTTP API multifactor action, e.g. {"secret_code":"123456"} for TOTP.

clientInfo ( clientInfo ): Information about the client that initiated the login. Unknown fields are ignored.

}

clientInfo - Information about the client that initiated the login. Unknown fields are ignored.
{

userAgent ( string ): The user agent of the client (currently not evaluated)

ip ( string ): The IP address of the client (currently not evaluated)

host ( string ): The user-facing host the login is performed against. Required by host-aware providers like WebAuthn/U2F to derive the relying party's origin.

}
Responses:
200:

The challenge to answer

Content-type: application/json

ExternalAuthMultifactorChallengeResponse - The challenge issued for the device
{

challenge ( challenge ): The provider-specific challenge data, the same as for the corresponding HTTP API multifactor action. Omitted if the provider issues no challenge.

}
400:

In case the action parameter is missing (MISSING_PARAMETER) or unknown (INVALID_PARAMETER_VALUE), the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), userId or contextId is missing or not numeric (MFA-0013), the provider is unknown (MFA-0006), a provider misses a parameter of the answer (MFA-0013), or another error of category USER_INPUT occurs, e.g. a missing providerName or deviceId, an unknown device or a wrong answer

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case permission is denied, e.g. an invalid authentication factor

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons, e.g. an unknown user

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Start the authentication with a TOTP device
POST http://localhost:8009/authentication/v1/multifactor?action=startAuthentication Content-Type: application/json {"userId":"3","contextId":"1","providerName":"TOTP","deviceId":"2f0c8e5a","clientInfo":{"host":"appsuite.example.com"}}
POST /authentication/v1/oidc/authorize-url Builds the OpenID Connect authorization request for a login init
Builds the OpenID provider's authorization request URI for a login init and stores the request state, so that the later authentication callback can be validated and resumed. State and nonce are created by the middleware, and the back-end's customization of the authorization request applies.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthOidcAuthorizeUrlBody - What a login init needs for the OpenID provider's authorization request. State and nonce are not part of it, the middleware creates and stores those. Unknown fields are ignored.
{

backendPath ( string ): The OpenID Connect back-end path, empty or absent for the default back-end

deepLink ( string ): The deep link to resume once the login has returned

reauth ( boolean ): Whether the provider must re-authenticate the user even if it holds a session of its own (max_age=0)

issuer ( string ): The iss of a third-party-initiated login, checked against the back-end's configured issuer before anything is built. Absent for a regular login init.

}
Responses:
200:

The authorization request URI

Content-type: application/json

ExternalAuthOidcAuthorizeUrlResponse - The authorization request of a login init
{

authorizeUrl ( string ): The authorization request URI the browser is to be redirected to

}
400:

In case the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), the back-end path is unknown, or a third-party-initiated login names an issuer that does not match the back-end's one

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case of an error of category PERMISSION_DENIED

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
503:

In case OpenID Connect is not available

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Initiate a login at the default back-end
POST http://localhost:8009/authentication/v1/oidc/authorize-url Content-Type: application/json {"deepLink":"#!!&app=io.ox/mail","reauth":false}
POST /authentication/v1/oidc/end-sessions Ends the OpenID provider's sessions behind sessions that ended elsewhere
Ends the OpenID provider's sessions behind the given sessions, which were not terminated by the client itself but by other means, e.g. by expiry or by an administrator. Whether a session is ended at the provider is decided per user by the configured opLogoutOnSessionRemoval reasons; sessions without an ID token and back-end paths that no longer resolve are passed over. The logout at the provider runs asynchronously and is retried.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthOidcEndSessionsBody - The sessions that ended elsewhere, and why. Sessions of any number of users may be passed in one call. Unknown fields are ignored.
{

removalReason ( string ): Why the sessions ended, matched case-insensitively against UNKNOWN, EXPIRED, INVALIDATED, USER_LOGOUT, USER_CLOSED and ADMIN_CLOSED. Whether the provider's sessions are ended at all is decided per user by the configured opLogoutOnSessionRemoval reasons. An absent or unknown reason is not an error, it simply ends no session.

endedSessions ( array[ExternalAuthOidcEndedSession] ): The sessions that ended

}

ExternalAuthOidcEndedSession - A session that ended elsewhere. Unknown fields are ignored.
{

backendPath ( string ): The OpenID Connect back-end path, empty or absent for the default back-end

userId ( integer ): The identifier of the user the session belonged to

contextId ( integer ): The identifier of that user's context

idToken ( string ): The ID token of the session, used as id_token_hint. Sessions without one are skipped.

}
Responses:
200:

The number of sessions accepted for logout

Content-type: application/json

ExternalAuthOidcEndSessionsResponse - The outcome of ending the provider's sessions
{

accepted ( integer ): The number of sessions accepted for logout at the provider. The logout itself runs asynchronously, so this is not the number of sessions the provider confirmed.

}
400:

In case the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY)

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
500:

In case the response cannot be written

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
503:

In case OpenID Connect is not available

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: End the provider's sessions of sessions closed by an administrator
POST http://localhost:8009/authentication/v1/oidc/end-sessions Content-Type: application/json {"removalReason":"ADMIN_CLOSED","endedSessions":[{"userId":3,"contextId":1,"idToken":"eyJhbGciOi..."}]}
POST /authentication/v1/oidc/handoff Redeems an OpenID Connect flow token
Redeems the flow token handed out at the end of the authorization code flow for the resolved identity and the associated token set, so that the external authentication component can own the durable session. The flow token is consumed.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthOidcHandoffBody - The flow token to redeem. Unknown fields are ignored.
{

flowToken ( string , required ): The one-time flow token (session reservation token) handed out by the middleware at the end of the authorization code flow. It is consumed by the request.

}
Responses:
200:

The identity and token set behind the flow token

Content-type: application/json

ExternalAuthOidcHandoff - The identity and token set behind a redeemed flow token, from which the external authentication component builds its session
{

userId ( integer ): The user identifier

contextId ( integer ): The context identifier

backendPath ( string ): The OpenID Connect back-end path the flow originated from, null for the default back-end

tokens ( ExternalAuthOidcTokenSet ): An OAuth/OpenID Connect token set

scopes ( array[string] ): The scopes granted to the session; the single scope * (full access) if none are restricted

schema ( integer ): The numeric suffix of the name of the database schema the user's context lives in, e.g. 7 for oxdatabase_7

}

ExternalAuthOidcTokenSet - An OAuth/OpenID Connect token set
{

accessToken ( string ): The access token

refreshToken ( string ): The refresh token, null if the provider issued none

idToken ( string ): The ID token

expiryMillis ( integer ): When the access token expires, as milliseconds since 1970-01-01 00:00:00 UTC; null if unknown

}
400:

In case the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), or the flow token is missing, unknown, expired or denotes no OpenID Connect reservation

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case of an error of category PERMISSION_DENIED

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
503:

In case OpenID Connect is not available

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Redeem a flow token
POST http://localhost:8009/authentication/v1/oidc/handoff Content-Type: application/json {"flowToken":"5c1f0d3e8b2a4f6c9d7e1a2b3c4d5e6f"}
POST /authentication/v1/oidc/logout Builds the OpenID Connect end-session request
Builds the OpenID provider's end-session (RP-initiated logout) request URI the browser is to be redirected to. Nothing is sent to the provider, the browser performs the logout by following the URI. The post_logout_redirect_uri is taken from the back-end configuration. To end the provider's sessions without a browser, see /authentication/v1/oidc/end-sessions.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthOidcLogoutBody - What the OpenID provider's end-session request URI is built from. Unknown fields are ignored.
{

backendPath ( string ): The OpenID Connect back-end path, empty or absent for the default back-end

idToken ( string ): The ID token to use as id_token_hint

state ( string ): The opaque value to round-trip through the provider, so that the caller can restore its post-logout context. A fresh random value is used if absent or empty.

}
Responses:
200:

The end-session request URI

Content-type: application/json

ExternalAuthOidcLogoutResponse - The end-session request of an RP-initiated logout
{

redirectUri ( string ): The end-session request URI the browser is to be redirected to

}
400:

In case the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), the back-end path is unknown, or the ID token is missing or cannot be parsed

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case of an error of category PERMISSION_DENIED

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
503:

In case OpenID Connect is not available

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Build the end-session request
POST http://localhost:8009/authentication/v1/oidc/logout Content-Type: application/json {"idToken":"eyJhbGciOi...","state":"b3BhcXVlLXN0YXRl"}
POST /authentication/v1/oidc/logout-token/verify Validates an OpenID Connect back-channel logout token
Validates the back-channel logout token the OpenID provider sent and returns the claims identifying the session the logout applies to.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthOidcVerifyLogoutTokenBody - The back-channel logout token to validate. Unknown fields are ignored.
{

backendPath ( string ): The OpenID Connect back-end path. Empty or absent for a provider-initiated logout that names no back-end, in which case the back-end is resolved by the token's issuer.

logoutToken ( string , required ): The raw back-channel logout token (JWT) as received from the OpenID provider

}
Responses:
200:

The identifying claims of the logout token

Content-type: application/json

ExternalAuthOidcLogoutTokenInfo - The identifying claims of a validated back-channel logout token
{

sid ( string ): The OpenID provider's session identifier (sid claim)

subject ( string ): The subject (sub claim)

}
400:

In case the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), the logout token is missing or not valid, or no back-end is found for the given path or the token's issuer

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case of an error of category PERMISSION_DENIED

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case of internal server error that might have multiple reasons

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
503:

In case OpenID Connect is not available

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Validate a logout token
POST http://localhost:8009/authentication/v1/oidc/logout-token/verify Content-Type: application/json {"logoutToken":"eyJhbGciOi..."}
POST /authentication/v1/oidc/refresh Refreshes an OpenID Connect token set
Renews the given token set at the OpenID provider, using the back-end's client authentication.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthOidcRefreshBody - The token set to renew and the user whose session it belongs to. The user is named because the refresh is performed with the back-end's client authentication on that user's behalf. Unknown fields are ignored.
{

backendPath ( string ): The OpenID Connect back-end path, empty or absent for the default back-end

accessToken ( string ): The access token to renew

refreshToken ( string ): The refresh token. Required, a token set without one cannot be renewed.

idToken ( string ): The ID token of the session

expiryMillis ( integer ): When the access token expires, as milliseconds since 1970-01-01 00:00:00 UTC

userId ( integer ): The identifier of the user the session belongs to

contextId ( integer ): The identifier of that user's context

}
Responses:
200:

The renewed token set

Content-type: application/json

ExternalAuthOidcTokenSet - An OAuth/OpenID Connect token set
{

accessToken ( string ): The access token

refreshToken ( string ): The refresh token, null if the provider issued none

idToken ( string ): The ID token

expiryMillis ( integer ): When the access token expires, as milliseconds since 1970-01-01 00:00:00 UTC; null if unknown

}
400:

In case the request body is missing, null or cannot be parsed (INVALID_JSON_REQUEST_BODY), it carries no accessToken (MISSING_PARAMETER), or the back-end path is unknown

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
401:

Not authorized
403:

In case the refresh cannot succeed anymore, because no refresh token was given or the OpenID provider permanently rejects it, e.g. because of an invalid refresh token or ID token (OIDC-0029). The token set cannot be renewed anymore, the session is to be ended.

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
500:

In case the refresh failed temporarily (OIDC-0018), or of internal server error that might have multiple reasons

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
503:

In case OpenID Connect is not available

Content-type: application/json

ExternalAuthError - The standard middleware error object describing why a request was rejected. It is meant to be relayed to the client by the calling external authentication component.
{

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 error, if known.

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. LGI-0006.

categories ( string ): The upper-case category identifier the error belongs to, e.g. USER_INPUT. An array of such identifiers if the error belongs to more than one category.

category ( integer ): Maintained for legacy reasons: The numeric representation of the first category.

}
Examples:

Example: Refresh a token set
POST http://localhost:8009/authentication/v1/oidc/refresh Content-Type: application/json {"accessToken":"eyJhbGciOi...","refreshToken":"eyJhbGciOi...","idToken":"eyJhbGciOi...","expiryMillis":1790000000000,"userId":3,"contextId":1}
POST /authentication/v1/resolve Resolves a user to its user, context and database schema
Resolves the given user to the user identifier, the context identifier and the database schema the user's context lives in. The user is denoted either by its context and user login names, or by an opaque identity that a deployment-specific resolver translates.

Security:
This security scheme must be used:

Name Scopes

basicAuth

Body:
Description:

No description available

Content-type: application/json

ExternalAuthResolveIdentityBody - The user that is supposed to be resolved. Exactly one of loginInfo and identity must be given.
{

loginInfo ( loginInfo ): The context and user login names as they are known to the middleware, for a caller that has already mapped its identity provider's response onto them. Both are looked up as-is, no further splitting or normalization takes place. Must not be combined with identity.

identity ( identity ): An opaque identifier that the caller cannot map onto login names itself, to be translated by a deployment-specific resolver. Must not be combined with loginInfo.

}

loginInfo - The context and user login names as they are known to the middleware, for a caller that has already mapped its identity provider's response onto them. Both are looked up as-is, no further splitting or normalization takes place. Must not be combined with identity.
{

contextName ( string , required ): The context login name, e.g. example.com

userName ( string , required ): The user login name, e.g. jane.doe

}

identity - An opaque identifier that the caller cannot map onto login names itself, to be translated by a deployment-specific resolver. Must not be combined with loginInfo.
{

type ( string , required ): The identifier's scheme, agreed upon between the caller and the resolver that handles it, e.g. subject:nameID

value ( string , required ): The identifier itself

}
Responses:
200:

The resolved identity

Content-type: application/json

ExternalAuthResolvedIdentity - The data a given user identity has been resolved to
{

userId ( string , required ): The identifier of the resolved user

cid ( string , required ): The identifier of the context the resolved user belongs to

schema ( integer , required ): The numeric suffix of the name of the database schema the user's context lives in, e.g. 7 for oxdatabase_7, or 0 if the schema name carries no numeric suffix

}
400:

In case the request body is invalid, denotes no user at all, or sets both loginInfo and identity at the same time

Content-type: application/json

Unknown
401:

Not authorized
404:

In case no resolver is able to resolve the given user
500:

In case of internal server error that might have multiple reasons. Response contains error message.

Content-type: application/json

Unknown
Examples:

Example: Resolve a user by its login names
POST http://localhost:8009/authentication/v1/resolve Content-Type: application/json {"loginInfo":{"contextName":"example.com","userName":"john.doe"}}

Example: Resolve a user by an opaque identity
POST http://localhost:8009/authentication/v1/resolve Content-Type: application/json {"identity":{"type":"subject:nameID","value":"john.doe@example.com"}}

DAVx5

DAVx5 Select configuration endpoint for initial setup and customization re-queries.

GET /davx5/v1/config/{token} Retrieves the DAVx5 Select configuration for a user.

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 the config query parameter and calls this endpoint.

Authenticated re-query (Basic Auth header): Returns customization-only JSON with Cache-Control and ETag headers 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/abc123token

Example2: Authenticated re-query (Basic Auth)

GET https://example.com/davx5/v1/config/abc123token -H "Authorization: Basic dXNlcjpwYXNz"

Health

The health-check module
- GET /health Get health status
  Responses:
  200:
  
  A JSON object containing health data
  
  Content-type: application/json
  
  HealthData
  {
  
  status ( string , possibleValues:
  
  UP
  
  DOWN
  
  ): The health overall status
  
  checks ( array[HealthCheckData] ): No description available
  
  service ( ServiceData ): No description available
  
  blacklist ( array[string] ): Blacklisted health checks
  
  ignorelist ( array[string] ): Ignored health checks
  
  }
  
  HealthCheckData
  {
  
  name ( string ): The health-check's name
  
  status ( string , possibleValues:
  
  UP
  
  DOWN
  
  ): The health-check's status
  
  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 status
  GET http://localhost:8009/health

InternetFreeBusy

Servlet for requesting free busy data.

GET /servlet/webdav.freebusy Gets the free busy data in iCalendar format.

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
- GET /metrics Gets appsuite metrics in the prometheus format
  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.

Migration

This module contains endpoints relevant to managing migrations

DELETE /migration/v1/migration/{id} Cancels a migration

GET /migration/v1/migrations Gets all migrations
Responses:
200:

A JSON object containing the migrations

Content-type: application/json

Migration - A migration
{

migrationId ( string ): The ID of the migration

name ( string ): The name of the migration

schemaName ( string ): The name of the database schema

dbPoolId ( integer ): The db pool id

reason ( string ): The reason for this migration

restriction ( string , possibleValues:

disabled

readOnly

none

): The restriction applied during this migration

startTime ( string ): The start time of this migration

status ( string , possibleValues:

notStarted

running

finished

error

): The status of this migration

}
500:

Internal server error.

POST /migration/v1/migrations/cancelAll Cancels all migration with the given name

Preliminary

This module contains preliminary endpoints which can change in the future.

GET /preliminary/capabilities/v1/all/{context}/{user} Gets all capabilities of a single user

GET /preliminary/chronos/v1/freebusy/{context} Gets the free/busy data of one or more users of a context

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:
  - INDIVIDUAL
  - GROUP
  - RESOURCE
  - ROOM
  - UNKNOWN
  ): The type of the calendar user. Users are reported as "INDIVIDUAL", queried resources and rooms as "RESOURCE" or "ROOM" accordingly.
- 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 address

GET 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

GET /preliminary/chronos/v1/freebusy/{context}/{user} Gets the free/busy data of a single user of a context

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:
  - INDIVIDUAL
  - GROUP
  - RESOURCE
  - ROOM
  - UNKNOWN
  ): The type of the calendar user. Users are reported as "INDIVIDUAL", queried resources and rooms as "RESOURCE" or "ROOM" accordingly.
- 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 user

GET http://localhost:8009/preliminary/chronos/v1/freebusy/1/3?from=2026-07-28T00:00:00Z&until=2026-08-04T00:00:00Z

GET /preliminary/configuration/v1/property/{property} Gets a single configuration property in server scope

GET /preliminary/configuration/v1/property/{property}/{context}/{user} Gets a single configuration property as resolved for a user

GET /preliminary/configuration/v1/withPrefix/{prefix} Gets all set configuration properties whose name starts with a prefix, in server scope

GET /preliminary/configuration/v1/withPrefix/{prefix}/{context}/{user} Gets all set configuration properties whose name starts with a prefix, as resolved for a user

GET /preliminary/crosscontext/v1/grants/{context} Lists the recorded cross-context grants of a whole context.

Lists, for every resource of the context that has one, the foreign contexts recorded in the owner-side cross-context grant index as holding access on it. The index is consulted directly rather than enumerating the context's entities, so only entities that effectively hold a grant appear.

Reports the index verbatim, with the same caveats as the per-entity variant: no backing store is consulted, there is no fallback when the index holds nothing, and the trust-zone authority is not applied.

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 hosting the resources.	path	integer

Responses:

200:

A JSON object describing the recorded grants of the context.

Content-type: application/json

Unknown
{
- context ( integer ): The context identifier.
- entities ( array[object] ): One entry per resource owner that holds at least one recorded grant.
}

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 every recorded cross-context grant of a context

GET http://localhost:8009/preliminary/crosscontext/v1/grants/1337

GET /preliminary/crosscontext/v1/grants/{context}/{entity} Lists the foreign contexts holding cross-context access on one resource.

Lists the contexts recorded in the owner-side cross-context grant index as holding access on the supplied resource - for a shared account, the contexts whose users or groups were granted a permission on it. It is the owner-side counterpart of the inbound liaison audit.

The result is keyed by grant type rather than by groupware module, because a grant can be module-less (SHARED_ACCOUNT is).

Reports the index verbatim: the backing stores are not consulted, there is no fallback when the index holds nothing, and the trust-zone authority is not applied. An empty grants object therefore means "nothing is recorded", not "nothing exists".

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 hosting the resource.	path	integer
entity	(empty)	The identifier of the resource owner within that context, e.g. the shared account.	path	integer

Responses:

200:

A JSON object describing the recorded grants.

Content-type: application/json

Unknown
{
- context ( integer ): The context identifier.
- entity ( integer ): The resource owner identifier.
- grants ( grants ): The recorded grants, as a mapping of grant type name to the list of grantee context identifiers. Only types with at least one grant are included.
}

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 contexts holding access on a shared account

GET http://localhost:8009/preliminary/crosscontext/v1/grants/1337/14

GET /preliminary/crosscontext/v1/inbound/{context} Lists the cross-context liaisons of the liaison-holding entities in a context.

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 context

GET http://localhost:8009/preliminary/crosscontext/v1/inbound/1337

GET /preliminary/crosscontext/v1/inbound/{context}/{user} Lists the cross-context liaisons and trust zones of a single user.

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 received

GET http://localhost:8009/preliminary/crosscontext/v1/inbound/1337/3

DELETE /preliminary/crosscontext/v1/inbound/{context}/{user} Retracts the cross-context access a single principal has received.

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, owner and module query 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 under skippedNoRetractor.

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 received

DELETE http://localhost:8009/preliminary/crosscontext/v1/inbound/1337/3

GET /preliminary/crosscontext/v1/outbound/{context}/{user} Lists the cross-context access a single user has granted out from its own resources.

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 out

GET http://localhost:8009/preliminary/crosscontext/v1/outbound/1337/3

DELETE /preliminary/crosscontext/v1/outbound/{context}/{user} Retracts the cross-context access a single user has granted out.

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) and module query 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 out

DELETE http://localhost:8009/preliminary/crosscontext/v1/outbound/1337/3

PUT /preliminary/http-notify/v1/notify Used by the dovecot mail server to push messages to the server
Body:
Description:

JSONObject containing the push message

Content-type: application/json

PushMessage
{

event ( string , possibleValues:

messageNew

): The event type.

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

}
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

GET /preliminary/mail/v1/validate-session/{session} Resolves a Middleware session and returns the IMAP backend coordinates plus credentials for the JMAP-IMAP proxy.

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's open-xchange-secret-<hash> cookie via the X-OX-Session-Secret header. 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.

Envelope — the success response is not returned in plain but wrapped as {"v":1,"envelope":"v1:<base64-iv>:<base64-ciphertext-with-tag>"}, encrypted with AES-256-GCM under the key derived from com.openexchange.mail.rest.encryption.key. The caller's Basic-Auth login (the trimmed value of com.openexchange.rest.services.basic-auth.login, UTF-8 bytes) is bound into the GCM tag as Associated Authenticated Data; the proxy must pass the identical bytes when decrypting. The decrypted plaintext is the JSON document described by the 200 response schema.

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:
  - LOGIN
  - XOAUTH2
  - OAUTHBEARER
  ): Authentication mode mirroring the Middleware-internal `AuthType` enum. `LOGIN` indicates the `secret` is a plaintext password; `XOAUTH2` and `OAUTHBEARER` indicate an OAuth2 access token.
- 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`.
}
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-Secret header is missing or mismatches the session's stored secret. The response body is the standard OX error JSON with code SES-0203 so 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 (code MAIL-0114), the endpoint requires TLS but the request is not secure (MAIL_REST-0004), or the source IP is not allow-listed (MAIL_REST-0005). The response body is the standard OX error JSON.

429:

The caller exceeded the per-minute rate limit. The response has no body.

500:

Unexpected error, or no authenticated caller identity is available on the server side (MAIL_REST-0009). The latter indicates a Middleware misconfiguration and must not be treated as an expired session.

503:

The encryption key is not configured or invalid (MAIL_REST-0006 / MAIL_REST-0007), or a required service is unavailable.

GET /preliminary/session/v1/get/{session} Resolves the given session id

GET /preliminary/sharedaccounts/v1/account Gets a specific shared account accessible by a user, referenced by email address or mail login

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 address

GET http://localhost:8009/preliminary/sharedaccounts/v1/account?userEmail=jane.doe@example.com&accountEmail=team@example.com

GET /preliminary/sharedaccounts/v1/accounts Gets the shared accounts accessible by a user, referenced by email address or mail login

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 address

GET http://localhost:8009/preliminary/sharedaccounts/v1/accounts?userEmail=jane.doe@example.com

GET /preliminary/sharedaccounts/v1/{context}/{user} Gets the shared accounts accessible by a user

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 user

GET http://localhost:8009/preliminary/sharedaccounts/v1/1/3

GET /preliminary/sharedaccounts/v1/{context}/{user}/{accountId} Gets a specific shared account accessible by a user

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 account

GET http://localhost:8009/preliminary/sharedaccounts/v1/1/3/5@1

GET /preliminary/utilities/mailResolver/v1/resolve/{mail*} Resolves the given mail addresses

Properties

This module contains property related operations
- GET /properties/v1/defaults Gets all property defaults
  Responses:
  200:
  
  A JSON object containing the property defaults
  
  500:
  
  Internal server error
Push

The push module
- PUT /chronos/v1/itip/pushmail Used by the dovecot mail server to push IMip Mails to the server
  Body:
  Description:
  
  JSONObject containing the push mail
  
  Content-type: application/json
  
  PushMail
  {
  
  event ( string , possibleValues:
  
  messageNew
  
  ): The event type.
  
  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
  
  }
  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

Userfeedback

The user feedback module

GET /userfeedback/v1/export/{context-group}/{type} Exports user feedback as CSV

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 CSV

GET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1?start=1451606400&end=1483228799

GET /userfeedback/v1/export/{context-group}/{type}/raw Exports user feedback

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-31

GET http://localhost:8009/userfeedback/v1/export/default/star-rating-v1/raw?start=1451606400&end=1483228799

POST /userfeedback/v1/send/{context-group}/{type} Exports user feedback and sends exported data to provided recipients

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.org

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

DELETE /userfeedback/v1/{context-group}/{type} Deletes user feedback

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-31

DELETE http://localhost:8009/userfeedback/v1/default/star-rating-v1?start=1451606400&end=1483228799

Parameter	Value	Description	Parameter Type	Data Type
name	(empty)	The user's login name	query	string
contextId	(empty)	The context id	query	long

Parameter	Value	Description	Parameter Type	Data Type
reseller	(empty)	The reseller name	query	string
package	(empty)	The package name	query	string

Parameter	Value	Description	Parameter Type	Data Type
property	(empty)	The fully-qualified name of the property to resolve	path	string
context	(empty)	The context id	path	long
user	(empty)	The user id	path	long

Parameter	Value	Description	Parameter Type	Data Type
prefix	(empty)	The property-name prefix to filter by, e.g. `com.openexchange.mail`	path	string
context	(empty)	The context id	path	long
user	(empty)	The user id	path	long

Introduction

Authentication

basicAuth

HTTP Basic Authentication.

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.

masterAdminAuth

The API can be accessed via HTTP Basic Auth with master administrator credentials.

OX REST API

Documentation of the Open-Xchange REST API.

Results

AccountRecovery

Body:

Responses:

204:

Parameters:

Responses:

200:

503:

Body:

Responses:

200:

204:

400:

403:

503:

Body:

Responses:

200:

400:

415:

Examples:

Parameters:

Responses:

200:

503:

Parameters:

Responses:

200:

400:

403:

410:

500:

503:

Body:

Responses:

200:

400:

403:

410:

500:

503:

Body:

Responses:

200:

400:

409:

410:

503:

Parameters:

Responses:

303:

400:

403:

410:

500:

503:

AccountRecoveryAdmin

Security:

basicAuth

Parameters:

Responses:

200:

400:

401:

404:

429:

500:

503:

Security: