Documentation Powered by ReDoc

${PRODUCT_NAME} - Middleware API (1.0.0)

Download OpenAPI specification:Download

Open-Xchange: info@open-xchange.com URL: https://www.open-xchange.com

The middleware API of ${PRODUCT_NAME} allows to manipulate the user accounts, filter profiles, devices, and all notifications of the user stored in the notification center.

Authentication

XApiKey

The API key for the provisioning API as specified in the server configuration.

Security scheme type: API Key
header parameter name: X-API-Key

Session

The session API to setup and destroy server-side user sessions.

Authenticate a user with password.

post /session/login
/$href(/api/v1)/session/login

Authenticates a user, and creates a new server session for the user specified in the request body. The session identifier will be stored in the response cookie protect-sid. If the user has two-factor authentication enabled, a token will be sent to the email address or phone number. That token needs to be sent with the route /session/login/token to fully authenticate the user.

Request Body schema:
application/json
password
required
string >= 6 characters

The password of the user.

username
required
string [ 1 .. 50 ] characters

The middleware identifier of the user.

Responses

200

User authentication successful. In case of two-factor authentication, the server awaits sending the token now (see /session/login/token).

400

Malformed request body data.

401

Invalid user name, or wrong password.

500

Unexpected error (internal server error).

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "password": "string",
  • "username": "string"
}

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Send another token for two-factor authentication.

post /session/login/requesttoken
/$href(/api/v1)/session/login/requesttoken

If the user authenticated with the route /session/login has two-factor authentication enabled, a token has been sent to the email address or phone number. This route allows to generate and send another token to the user which will be expected to be returned with the route /session/login/token afterwards.

Responses

200

New token has been sent successfully.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Authenticate a user with the generated two-factor authentication token.

post /session/login/token
/$href(/api/v1)/session/login/token

If the user authenticated with the route /session/login has two-factor authentication enabled, a token has been sent to the email address or phone number. That token needs to be sent with this route to fully authenticate the user.

Request Body schema:
application/json
token
required
string >= 4 characters

The authentication token that has been sent to the user.

Responses

200

User authentication successful.

400

Malformed request body data.

401

Invalid user name, or wrong token.

500

Unexpected error (internal server error).

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "token": "string"
}

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Invalidate a server session.

post /session/logout
/$href(/api/v1)/session/logout

Invalidates the server session identified by the request cookie protect-sid.

Responses

200

Server session has been invalidated successfully.

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Users

The user API to manage global settings of a user account.

Return the static configuration of an existing user account.

get /user/{user_id}/config
/$href(/api/v1)/user/{user_id}/config

Returns the static configuration (classification platforms, categories, and presets) of an existing user account, according to the device mode.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

Responses

200

User configuration found and returned successfully.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

User does not exist (wrong user identifier in URL).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "categories":
    [
    ],
  • "device_mode": true,
  • "engines":
    [
    ],
  • "platforms":
    [
    ],
  • "presets":
    [
    ]
}

Return the settings of an existing user account.

get /user/{user_id}/settings
/$href(/api/v1)/user/{user_id}/settings

Returns the settings of an existing user account.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

Responses

200

User account found and returned successfully.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

User does not exist (wrong user identifier in URL).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "phone_2fa": "string",
  • "profile_wizard_shown": true,
  • "user_id": "string"
}

Modify the settings of an existing user account.

patch /user/{user_id}/settings
/$href(/api/v1)/user/{user_id}/settings

Modifies the settings of an existing user account.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

Request Body schema:
application/json
email_2fa
string [ 1 .. 100 ] characters

The email address used to send an email with the token for two-factor authentication.

has_2fa
boolean

Whether the user will use two-factor authentication with an additional token sent to an email address or to a phone number.

locale
string [ 1 .. 32 ] characters

The locale of the user, e.g. en-US.

phone_2fa
string [ 1 .. 40 ] characters

The phone number used to send an SMS with the token for two-factor authentication.

profile_wizard_shown
boolean

Whether the initial profile wizard has been shown in the web application.

user_id
required
string [ 1 .. 50 ] characters

The middleware identifier of the user (used in the URLs of the middleware API).

Responses

200

User account updated successfully.

400

Malformed request body data.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

User does not exist (wrong user identifier in URL).

500

Unexpected error (internal server error).

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "phone_2fa": "string",
  • "profile_wizard_shown": true,
  • "user_id": "string"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "phone_2fa": "string",
  • "profile_wizard_shown": true,
  • "user_id": "string"
}

Change the internal password of an existing user account.

patch /user/{user_id}/settings/password
/$href(/api/v1)/user/{user_id}/settings/password

Changes the internal password of an existing user account. If the user has been identified by URL parameter, or via identity server, this command allows to set the new password without having to know the current password (the property old_password in the request body will be ignored and can be omitted).

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

Request Body schema:
application/json
old_password
string >= 6 characters

The current password.

password
required
string >= 6 characters

The new password.

Responses

200

User account updated successfully.

400

Malformed request body data.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

User does not exist (wrong user identifier in URL).

500

Unexpected error (internal server error).

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "old_password": "string",
  • "password": "string"
}

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Profiles

The profile API to manage the user's filter profiles.

Create a new filter profile in an existing user account.

put /user/{user_id}/profile
/$href(/api/v1)/user/{user_id}/profile

Creates a new filter profile in an existing user account. The identifier of the new filter profile will be set to the first available free profile identifier in the user account.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

query Parameters
oneway
boolean

If set to true, the server response will not contain the complete settings of the filter profile but a JSON object containing the property profile_id with the profile identifier only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases.

Request Body schema:
application/json
avatar_version
integer >= 0

A unique positive integer for the current avatar image (can be used to bypass browser cache when getting the avatar image). Will be zero, if there is no avatar image available for the profile. Otherwise, the value of this property does not matter, especially it cannot be used to get older versions of an avatar image. This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile. See route /user/{user_id}/profile/{profile_id}/avatar.

bedtime_weekend
object (OfftimeSchedule)

Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys fr and sa (Friday and Saturday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

bedtime_workdays
object (OfftimeSchedule)

Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys su, mo, tu, we, and th (Sunday to Thursday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

blacklist
Array of string (DomainList)

A list with domain names that will always be blocked, regardless of other filtering settings in the profile (except the domains listed in teh property whitelist).

categories
Array of string (CategoryList)

The identifiers of all classification categories to be blocked, and of all platforms to be allowed. If this property will be set, the property preset will be set to "custom" automatically.

disabled_duration
integer >= 0

Content-based filtering will be manually disabled temporarily for this duration from now, in seconds. If set to zero, content-based filtering has not been disabled temporarily. Changing this property will automatically change the value of the property disabled_until too. The result of changing both properties at the same time is undefined.

disabled_until
integer >= 0

Content-based filtering has been manually disabled temporarily until this date and time, as UNIX timestamp in seconds (UTC, zero is 1970-01-01 at midnight). Changing this property will automatically change the value of the property disabled_duration too. The result of changing both properties at the same time is undefined.

filter_content
boolean

Whether content-based filtering is enabled.

  • If this property will be set to false, the property preset will be set to the value "none" automatically.
  • If this property will be set to true, the previous value of the property preset will be restored.
filter_security
boolean

Whether virus/malware filtering is enabled.

homework_schedule
object (HomeworkSchedule)

Homework time settings with categories to be blocked, and platforms to be allowed while activated.

name
string <= 50 characters

The user-defined name of the filter profile.

offtime_schedules
Array of object (OfftimeSchedule)

All existing offtime settings, as a dynamic array with unlimited number of elements.

pause_internet
boolean

Whether internet access is currently disabled completely.

preset
string non-empty

The identifier of a predefined set of classification categories, or "custom" for a user-defined set, or "none", if content filtering is disabled (property filter_content is false).

  • If this property will be set to an existing preset list, the property categories will be updated automatically.
  • If this property will be set to the value "none", the property filter_content will be set to false automatically (no content filtering, no blacklist or whitelist).
profile_id
required
integer >= 0

The unique identifier of the filter profile (used in the URLs of the middleware API). This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (the profile identifier will be set automatically).

user_id
required
string [ 1 .. 50 ] characters

The middleware identifier of the user owning the filter profile. This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (user will be identified via URL or session).

whitelist
Array of string (DomainList)

A list with domain names that will never be blocked, regardless of other filtering settings in the profile.

Responses

200

Filter profile created successfully.

400

Malformed request body data.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

User does not exist (wrong user identifier in URL).

422

Invalid property values in request body data.

500

Unexpected error (internal server error).

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "avatar_version": 0,
  • "bedtime_weekend":
    {
    },
  • "bedtime_workdays":
    {
    },
  • "blacklist":
    [
    ],
  • "categories":
    [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule":
    {
    },
  • "name": "string",
  • "offtime_schedules":
    [
    ],
  • "pause_internet": true,
  • "preset": "string",
  • "profile_id": 0,
  • "user_id": "string",
  • "whitelist":
    [
    ]
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "avatar_version": 0,
  • "bedtime_weekend":
    {
    },
  • "bedtime_workdays":
    {
    },
  • "blacklist":
    [
    ],
  • "categories":
    [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule":
    {
    },
  • "name": "string",
  • "offtime_schedules":
    [
    ],
  • "pause_internet": true,
  • "preset": "string",
  • "profile_id": 0,
  • "user_id": "string",
  • "whitelist":
    [
    ]
}

Delete an existing filter profile.

delete /user/{user_id}/profile/{profile_id}
/$href(/api/v1)/user/{user_id}/profile/{profile_id}

Deletes the settings of an existing filter profile.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

profile_id
required
integer >= 0

The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account.

Responses

200

Resource deleted successfully.

204

Nothing to delete (resource not found).

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

403

Default profile (profile identifier 0) cannot be deleted.

404

User does not exist (wrong user identifier in URL).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Return an existing filter profile.

get /user/{user_id}/profile/{profile_id}
/$href(/api/v1)/user/{user_id}/profile/{profile_id}

Returns the settings of an existing filter profile.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

profile_id
required
integer >= 0

The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account.

Responses

200

Filter profile found and returned successfully.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

Filter profile or user account do not exist (wrong profile identifier or user identifier in URL).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "avatar_version": 0,
  • "bedtime_weekend":
    {
    },
  • "bedtime_workdays":
    {
    },
  • "blacklist":
    [
    ],
  • "categories":
    [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule":
    {
    },
  • "name": "string",
  • "offtime_schedules":
    [
    ],
  • "pause_internet": true,
  • "preset": "string",
  • "profile_id": 0,
  • "user_id": "string",
  • "whitelist":
    [
    ]
}

Modify an existing filter profile.

patch /user/{user_id}/profile/{profile_id}
/$href(/api/v1)/user/{user_id}/profile/{profile_id}

Modifies the settings of an existing filter profile.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

profile_id
required
integer >= 0

The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account.

query Parameters
oneway
boolean

If set to true, the server response will not contain the specified JSON data but an empty object only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases.

Request Body schema:
application/json
avatar_version
integer >= 0

A unique positive integer for the current avatar image (can be used to bypass browser cache when getting the avatar image). Will be zero, if there is no avatar image available for the profile. Otherwise, the value of this property does not matter, especially it cannot be used to get older versions of an avatar image. This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile. See route /user/{user_id}/profile/{profile_id}/avatar.

bedtime_weekend
object (OfftimeSchedule)

Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys fr and sa (Friday and Saturday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

bedtime_workdays
object (OfftimeSchedule)

Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys su, mo, tu, we, and th (Sunday to Thursday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

blacklist
Array of string (DomainList)

A list with domain names that will always be blocked, regardless of other filtering settings in the profile (except the domains listed in teh property whitelist).

categories
Array of string (CategoryList)

The identifiers of all classification categories to be blocked, and of all platforms to be allowed. If this property will be set, the property preset will be set to "custom" automatically.

disabled_duration
integer >= 0

Content-based filtering will be manually disabled temporarily for this duration from now, in seconds. If set to zero, content-based filtering has not been disabled temporarily. Changing this property will automatically change the value of the property disabled_until too. The result of changing both properties at the same time is undefined.

disabled_until
integer >= 0

Content-based filtering has been manually disabled temporarily until this date and time, as UNIX timestamp in seconds (UTC, zero is 1970-01-01 at midnight). Changing this property will automatically change the value of the property disabled_duration too. The result of changing both properties at the same time is undefined.

filter_content
boolean

Whether content-based filtering is enabled.

  • If this property will be set to false, the property preset will be set to the value "none" automatically.
  • If this property will be set to true, the previous value of the property preset will be restored.
filter_security
boolean

Whether virus/malware filtering is enabled.

homework_schedule
object (HomeworkSchedule)

Homework time settings with categories to be blocked, and platforms to be allowed while activated.

name
string <= 50 characters

The user-defined name of the filter profile.

offtime_schedules
Array of object (OfftimeSchedule)

All existing offtime settings, as a dynamic array with unlimited number of elements.

pause_internet
boolean

Whether internet access is currently disabled completely.

preset
string non-empty

The identifier of a predefined set of classification categories, or "custom" for a user-defined set, or "none", if content filtering is disabled (property filter_content is false).

  • If this property will be set to an existing preset list, the property categories will be updated automatically.
  • If this property will be set to the value "none", the property filter_content will be set to false automatically (no content filtering, no blacklist or whitelist).
profile_id
required
integer >= 0

The unique identifier of the filter profile (used in the URLs of the middleware API). This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (the profile identifier will be set automatically).

user_id
required
string [ 1 .. 50 ] characters

The middleware identifier of the user owning the filter profile. This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (user will be identified via URL or session).

whitelist
Array of string (DomainList)

A list with domain names that will never be blocked, regardless of other filtering settings in the profile.

Responses

200

Filter profile updated successfully.

400

Malformed request body data.

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

Filter profile or user account do not exist (wrong profile identifier or user identifier in URL).

500

Unexpected error (internal server error).

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "avatar_version": 0,
  • "bedtime_weekend":
    {
    },
  • "bedtime_workdays":
    {
    },
  • "blacklist":
    [
    ],
  • "categories":
    [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule":
    {
    },
  • "name": "string",
  • "offtime_schedules":
    [
    ],
  • "pause_internet": true,
  • "preset": "string",
  • "profile_id": 0,
  • "user_id": "string",
  • "whitelist":
    [
    ]
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "avatar_version": 0,
  • "bedtime_weekend":
    {
    },
  • "bedtime_workdays":
    {
    },
  • "blacklist":
    [
    ],
  • "categories":
    [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule":
    {
    },
  • "name": "string",
  • "offtime_schedules":
    [
    ],
  • "pause_internet": true,
  • "preset": "string",
  • "profile_id": 0,
  • "user_id": "string",
  • "whitelist":
    [
    ]
}

Delete the avatar image from an existing filter profile.

delete /user/{user_id}/profile/{profile_id}/avatar
/$href(/api/v1)/user/{user_id}/profile/{profile_id}/avatar

Deletes the avatar image from an existing filter profile.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user. The API supports several ways to identify the user sending a request:

  • URL Parameter: The user identifier is contained directly in this parameter, e.g. the user john in the API request GET $href(/api/v1/user/john/settings). This type of identification requires to supply an API token. This API token needs to be passed in the HTTP header field X-API-Key: <token>, or in the HTTP header field Authorization: Token <token> (note that the keyword Token is required in front of the actual token).

  • Identity Server: A user can be identified by using the special user identifier - (a simple dash character), and an (OAuth2) access token with Token Introspection (RFC 7662) at an identity server. The access token needs to be passed as Bearer Token (RFC 6750) in the HTTP header field Authorization: Bearer <token> (note that the keyword Bearer is required in front of the actual token). This access token will be generated during login at the identity server. This kind of identification does not require an API token (X-API-Key).

  • Server Session: A user can be identified by using the special user identifier - (a simple dash character), and a session identifier in the request cookie protect-sid, e.g. in the request GET $href(/api/v1/user/-/settings). This kind of identification does not require an API token (X-API-Key).

profile_id
required
integer >= 0

The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account.

Responses

200

Resource deleted successfully.

204

Nothing to delete (resource not found).

401

Unauthorized (missing or invalid session identifier, or missing or wrong API token).

404

Filter profile or user account do not exist (wrong profile identifier or user identifier in URL).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
 Expand all Collapse all
{ }