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

• Admin

  Interface for provisioning and other administrative operations.
  Show/Hide List Operations Expand 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

    Security:

    This security scheme must be used:

    Name	Scopes
    masterAdminAuth

    
    

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    global	(empty)	Close sessions cluster-wide. Default: true	query	boolean

    Body:

    Description:

    A JSON object containing an array of session ids.

    Content-type: application/json

    • CloseSessionsByIdBody
      {

      • sessionIds ( array[string] ): Array of session IDs

      }

    
    

    Responses:

    200:

    OK

    400:

    Bad request, response contains error message.

    401:

    Not authorized

    403:

    Forbidden

    404:

    Not found. If path is wrong. Response contains error message.

    500:

    Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.

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

    Security:

    This security scheme must be used:

    Name	Scopes
    masterAdminAuth

    
    

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    global	(empty)	Close sessions cluster-wide. Default: true	query	boolean

    Body:

    Description:

    A JSON object containing an array of user and context id tuples.

    Content-type: application/json

    • CloseSessionByUserBody
      {

      • users ( array[object] ): Array of context/user id tuples

      }

    
    

    Responses:

    200:

    OK

    400:

    Bad request, response contains error message.

    401:

    Not authorized

    403:

    Forbidden

    404:

    Not found. If path is wrong. Response contains error message.

    500:

    Internal server error that might have multiple reasons, for instance no configured global database. Response contains error message.

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

    Security:

    This security scheme must be used:

    Name	Scopes
    contextAdminAuth

    
    

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    context-id	(empty)	The context the user is in	path	integer
    user-id	(empty)	The ID representing the user	path	integer

    Responses:

    200:

    All devices deleted

    401:

    Not authorized

    404:

    Not found. If path is wrong. Response contains error message.

    500:

    Internal server error that might have multiple reasons. Response contains error message.

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

    Security:

    This security scheme must be used:

    Name	Scopes
    contextAdminAuth

    
    

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    context-id	(empty)	The context the user is in	path	integer
    user-id	(empty)	The ID representing the user	path	integer
    provider-name	(empty)	The name of the provider to delete the device for	path	string
    device-id	(empty)	The ID of the device to delete	path	string

    Responses:

    200:

    If the device was deleted

    401:

    Not authorized

    404:

    Not found. If path is wrong, or if the given provider, or device was not found.

    500:

    Internal server error that might have multiple reasons. Response contains error message.

  • 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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The log level of the specified logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    401:

    Not authorized

    404:

    In case the context or the logger doesn't exist.

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer
    logger	(empty)	The name of the logger	path	string

    Body:

    Description:

    The log level for the given logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    Responses:

    200:

    The log level of a specified logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    400:

    In case the client sends an invalid body.

    401:

    Not authorized

    404:

    In case no logger with the given name exists

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The logger was successfully removed.

    401:

    Not authorized

    404:

    In case the no logger with the given name exists for the given context

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer

    Responses:

    200:

    An array of loggers.

    Content-type: application/json

    • Logger
      {

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

      }

    
    

    401:

    Not authorized

    404:

    In case no logger is configured for the given context id.

    500:

    Internal server error that might have multiple reasons.

  • 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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer

    Responses:

    200:

    The logger was successfully removed.

    401:

    Not authorized

    404:

    In case the no logger with the given name exists for the given session

    500:

    Internal server error that might have multiple reasons.

  • GET /admin/v1/logconf/context/{contextId}/user/{userId}/logger/{logger} Gets the log level of a logger 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
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The log level of a specified logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    401:

    Not authorized

    404:

    In case no logger with the given name exists or the context or the user doesn't exist

    500:

    Internal server error that might have multiple reasons.

  • PUT /admin/v1/logconf/context/{contextId}/user/{userId}/logger/{logger} Sets the log level of a logger 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
    logger	(empty)	The name of the logger	path	string

    Body:

    Description:

    The log level for the given logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    Responses:

    200:

    The log level of a specified logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    400:

    In case the client sends an invalid body.

    401:

    Not authorized

    404:

    In case the context or the user doesn't exist

    500:

    Internal server error that might have multiple reasons.

  • DELETE /admin/v1/logconf/context/{contextId}/user/{userId}/logger/{logger} Removes a logger 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
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The loggers were successfully removed.

    401:

    Not authorized

    404:

    In case the context, user or logger doesn't exist

    500:

    Internal server error that might have multiple reasons.

  • GET /admin/v1/logconf/context/{contextId}/user/{userId}/loggers Gets all 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

    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

    404:

    In case no logger is configured for the given context and user or if the context or user doesn't exist.

    500:

    Internal server error that might have multiple reasons.

  • 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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer
    userId	(empty)	The user id	path	integer

    Responses:

    200:

    The loggers were successfully removed.

    401:

    Not authorized

    404:

    In case the context or user doesn't exist

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer
    userId	(empty)	The user id	path	integer

    Responses:

    200:

    Successful operation

    Content-type: application/json

    • Unknown - true, if the stacktrace is included for the given user, false otherwise
      

    
    

    401:

    Not authorized

    404:

    In case the context or the user doesn't exist

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer
    userId	(empty)	The user id	path	integer

    Body:

    Description:

    Updates if a stacktrace should be included in a HTTP JSON error response to the given user.

    Content-type: application/json

    • Unknown - true, if the stacktrace should be included for the given user, false otherwise
      

    
    

    Responses:

    200:

    Successful operation

    400:

    In case the client sends an invalid body.

    401:

    Not authorized

    404:

    In case the context or the user doesn't exist

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	path	integer

    Responses:

    200:

    An array of users and their loggers.

    Content-type: application/json

    • UsersLoggers
      {

      • userId ( string ): The user id
      • loggers ( array[Logger] ): All loggers related to the user

      }
    • Logger
      {

      • name ( string , required ): The name of the logger
      • level ( LogLevel , required , possibleValues:
        • 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/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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    sessionId	(empty)	The session id	path	string
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The log level of a specified logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    401:

    Not authorized

    404:

    In case the no logger with the given name exists for the given session

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    sessionId	(empty)	The session id	path	string
    logger	(empty)	The name of the logger	path	string

    Body:

    Description:

    The log level for the given logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    Responses:

    200:

    The log level of the set logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    400:

    In case the client sends an invalid body.

    401:

    Not authorized

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    sessionId	(empty)	The session id	path	string
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The logger was successfully removed.

    401:

    Not authorized

    404:

    In case the no logger with the given name exists for the given session

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    sessionId	(empty)	The session id	path	string

    Responses:

    200:

    An array of loggers.

    Content-type: application/json

    • Logger
      {

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

      }

    
    

    401:

    Not authorized

    404:

    In case no logger is configured for the given session id.

    500:

    Internal server error that might have multiple reasons.

  • 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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    sessionId	(empty)	The session id	path	string

    Responses:

    200:

    All loggers were successfully removed.

    401:

    Not authorized

    500:

    Internal server error that might have multiple reasons.

  • 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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    logger	(empty)	The name of the logger	path	string

    Responses:

    200:

    The log level of a specified logger

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    401:

    Not authorized

    404:

    In case no logger with the given name exists

    500:

    Internal server error that might have multiple reasons.

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    logger	(empty)	The name of the logger	path	string

    Body:

    Description:

    The log level to set

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    Responses:

    200:

    The log level

    Content-type: application/json

    • LogLevel - The log level
      

    
    

    400:

    In case the client sends an invalid body.

    401:

    Not authorized

    404:

    In case no logger with the given name exists

    500:

    Internal server error that might have multiple reasons.

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

  ---

• Advertisement

  The advertisement module
  Show/Hide List Operations Expand Operations

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

    Parameters:

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

    Body:

    Description:

    JSONObject describing the advertisement configuration

    Content-type: application/json

    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    Parameters:

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

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    Parameters:

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

    Body:

    Description:

    JSONObject describing the advertisement configuration

    Content-type: application/json

    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    Parameters:

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

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    Parameters:

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

    Body:

    Description:

    JSONObject describing the advertisement configuration

    Content-type: application/json

    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	query	long
    userId	(empty)	The user id	query	long

    Body:

    Description:

    JSONObject describing the advertisement configuration

    Content-type: application/json

    • Unknown
      

    
    

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    contextId	(empty)	The context id	query	long
    userId	(empty)	The user id	query	long

    Responses:

    200:

    The configuration result

    400:

    Bad request, response contains error message.

    401:

    Not authorized

  ---

• Health

  The health-check module
  Show/Hide List Operations Expand Operations

  • 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.
  Show/Hide List Operations Expand Operations

  • 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
  Show/Hide List Operations Expand Operations

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

  ---

• Preliminary

  This module contains preliminary endpoints which can change in the future.
  Show/Hide List Operations Expand Operations

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    context	(empty)	The context id	path	long
    user	(empty)	The user id	path	long

    Responses:

    200:

    A JSON array containing the capabilities for the user
    

    Content-type: application/json

    
    

    401:

    Not authorized

    500:

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

    Content-type: application/json

    • Unknown
      

    
    

    Examples:

    Example: Get capabilities

    GET http://localhost:8009/preliminary/capabilities/v1/all/1/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/session/v1/get/{session} Resolves the given session id

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    session	(empty)	The session id	path	string

    Responses:

    200:

    A JSON object containing informations about the session.
    

    Content-type: application/json

    • Unknown - A json object containing informations about the session.
      {

      • context ( integer ): The context id.
      • user ( integer ): The user id.
      • guest ( boolean ): Whether the session belongs to a guest user or not.

      }

    
    

    401:

    Not authorized

    500:

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

    Content-type: application/json

    • Unknown
      

    
    

    Examples:

    Example: Resolve session

    GET http://localhost:8009/preliminary/session/v1/get/1234567890

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

    Parameters:

    Parameter	Value	Description	Parameter Type	Data Type
    mail*	(empty)	The mail addresses as a semicolon separated list	path	string

    Responses:

    200:

    A json object containg subobjects for every mail address which contains the user id, context id and addtional informations.
    

    401:

    Not authorized

    500:

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

    Examples:

    Example: Resolve addresses

    GET http://localhost:8009//preliminary/utilities/mailResolver/v1/resolve/anton@context1.ox.test;berta@context1.ox.test

  ---

• Push

  The push module
  Show/Hide List Operations Expand Operations

  • 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
      

    
    

  ---

• Request-Analysis

  This module contains endpoints used to analyze requests
  Show/Hide List Operations Expand Operations

  • POST /request-analysis/v1/analyze Analyzes the request

    Analyzes the request data and maps it to a marker if possible

    Security:

    This security scheme must be used:

    Name	Scopes
    basicAuth

    
    

    Body:

    Description:

    A json object describing the request

    Content-type: application/json

    • RequestData
      {

      • method ( string , required ): The method of the request
      • url ( string , required ): The url of the request
      • remoteIP ( string , required ): the remote ip of the request
      • headers ( array[object] , required ): An array of headers of the request
      • body ( string ): The body of the request as a base64 encoded string

      }

    
    

    Responses:

    200:

    Successful operation

    Content-type: application/json

    • AnalysisResult - An analysis result
      {

      • marker ( string , required ): No description available
      • headers ( headers ): An object containing headers which should be added to the request
      • type ( string ): No description available

      }
    • headers - An object containing headers which should be added to the request
      {

      • x-ox-context-id ( integer , required ): No description available
      • x-ox-user-id ( integer ): No description available
      • x-ox-login ( string ): No description available

      }

    
    

    400:

    In case a required field is missing

    404:

    Returned in case no marker could be found for the given request

    422:

    The body is required to determine the marker for the given request

    500:

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

    Content-type: application/json

    • Unknown
      

    
    

  ---

• Userfeedback

  The user feedback module
  Show/Hide List Operations Expand Operations

  • 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

  ---