Documentation Powered by ReDoc

OX Protect - Provisioning API (2.0.0)

Download OpenAPI specification:Download

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

The provisioning API of OX Protect middleware allows an administrator to receive, create, change, or delete user accounts in the middleware itself, as well as in the PowerDNS platform, and the notification center used by the middleware.

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

Users

The user API to manage single user accounts.

Create a new, or replace an existing user account.

Creates a new user account, or (optionally) replaces an existing user account.

Authorizations:
XApiKey
query Parameters
replace
boolean

If set to true, an existing user account (identified by the property user_id) will be replaced completely. By default, an existing user account leads to an error.

provision_pdns
boolean

If set to true, the PowerDNS platform account (identified by the property user_id_pdns) will be created too (or replaced if specified). By default, only the middleware user account will be created without modifying the PowerDNS platform.

provision_notify
boolean

If set to true, the user account in the notification center (identified by the property user_id_notify) will be created too (or replaced if specified). By default, only the middleware user account will be created without modifying the notification center.

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
application/json
application/x-www-form-urlencoded

The properties to be set for the new user account. Omitted properties will be set to their default values. Must contain the properties user_id and user_id_pdns at least.

locale
string [ 1 .. 32 ] characters

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

mail_active
boolean

Whether the registered email address will be used for notifications. This property is only available with query parameter provision_notify.

mail_address
string or null

The email address used in the notification center. This property is only available with query parameter provision_notify.

mail_filter_content
boolean

Whether to send email notifications for requests that have been blocked by content-based filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

mail_filter_security
boolean

Whether to send email notifications for requests that have been blocked by virus/malware filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

mail_new_device
boolean

Whether to send an email notification when a new device has been detected. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

password_hash
string or null [ 1 .. 100 ] characters

Bcrypt hash of the user password. Only required when not using an external authentication system.

phone_active
boolean

Whether the registered phone number will be used for notifications. This property is only available with query parameter provision_notify.

phone_filter_content
boolean

Whether to send sms notifications for requests that have been blocked by content-based filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

phone_filter_security
boolean

Whether to send sms notifications for requests that have been blocked by virus/malware filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

phone_new_device
boolean

Whether to send an sms notification when a new device has been detected. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

phone_number
string or null

The phone number used in the notification center. This property is only available with query parameter provision_notify.

profile_wizard_shown
boolean

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

push_active
boolean

Whether the registered push tokens for mobile devices will be used for push notifications. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

push_filter_content
boolean

Whether to send push notifications for requests that have been blocked by content-based filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

push_filter_security
boolean

Whether to send push notifications for requests that have been blocked by virus/malware filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

push_new_device
boolean

Whether to send a push notification when a new device has been detected. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

tfa_active
boolean

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

tfa_mail
string or null [ 1 .. 100 ] characters

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

tfa_phone
string or null [ 1 .. 40 ] characters

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

timezone
string or null [ 1 .. 100 ] characters

The time zone of the user, e.g. Australia/Sydney. Used for all profile settings with times, e.g. offtime and homework time schedules.

user_id
required
string [ 1 .. 50 ] characters

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

user_id_notify
string or null [ 1 .. 50 ] characters

The identifier of the user in the notification center.

user_id_oauth
string or null [ 1 .. 50 ] characters

The identifier of the user for authentication with OAuth2.

user_id_pdns
required
string [ 1 .. 40 ] characters

The identifier of the user in the notification center.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "password_hash": "string",
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Response samples

Content type
application/json
{
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "password_hash": "string",
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Delete an existing user account.

Deletes an existing user account with the specified middleware user identifier.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user.

query Parameters
provision_pdns
boolean

If set to true, the PowerDNS platform account (identified by the property user_id_pdns) will be deleted too. By default, only the middleware user account will be deleted without modifying the PowerDNS platform.

provision_notify
boolean

If set to true, the user account in the notification center (identified by the property user_id_notify) will be deleted too. By default, only the middleware user account will be deleted without modifying the notification center.

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return an existing user account.

Returns an existing user account with the specified middleware user identifier.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user.

query Parameters
provision_notify
boolean

If set to true, the notification settings of the user will be returned too. By default, only the middleware user settings will be returned without calling the notification center.

Responses

Response samples

Content type
application/json
{
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "password_hash": "string",
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Modify an existing user account.

Modifies an existing user account with the specified middleware user identifier.

Authorizations:
XApiKey
path Parameters
user_id
required
string

The middleware identifier of the user.

query Parameters
provision_pdns
boolean

If set to true, the user account in the PowerDNS platform (identified by the property user_id_pdns) will be updated too. By default, only the middleware user account will be updated without modifying the PowerDNS platform.

provision_notify
boolean

If set to true, the user account in the notification center (identified by the property user_id_notify) will be updated too. By default, only the middleware user account will be updated without modifying the notification center.

provision_create
boolean

If set to true, missing accounts in the PowerDNS platform or in the notification center will be created. By default, these accounts are expected to exist. This flag works only in conjunction with the query parameter provision_pdns and provision_notify respectively.

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
application/json
application/x-www-form-urlencoded

The properties to be changed for the user account. Omitted properties will not be modified.

locale
string [ 1 .. 32 ] characters

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

mail_active
boolean

Whether the registered email address will be used for notifications. This property is only available with query parameter provision_notify.

mail_address
string or null

The email address used in the notification center. This property is only available with query parameter provision_notify.

mail_filter_content
boolean

Whether to send email notifications for requests that have been blocked by content-based filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

mail_filter_security
boolean

Whether to send email notifications for requests that have been blocked by virus/malware filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

mail_new_device
boolean

Whether to send an email notification when a new device has been detected. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

password_hash
string or null [ 1 .. 100 ] characters

Bcrypt hash of the user password. Only required when not using an external authentication system.

phone_active
boolean

Whether the registered phone number will be used for notifications. This property is only available with query parameter provision_notify.

phone_filter_content
boolean

Whether to send sms notifications for requests that have been blocked by content-based filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

phone_filter_security
boolean

Whether to send sms notifications for requests that have been blocked by virus/malware filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

phone_new_device
boolean

Whether to send an sms notification when a new device has been detected. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

phone_number
string or null

The phone number used in the notification center. This property is only available with query parameter provision_notify.

profile_wizard_shown
boolean

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

push_active
boolean

Whether the registered push tokens for mobile devices will be used for push notifications. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

push_filter_content
boolean

Whether to send push notifications for requests that have been blocked by content-based filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

push_filter_security
boolean

Whether to send push notifications for requests that have been blocked by virus/malware filtering. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

push_new_device
boolean

Whether to send a push notification when a new device has been detected. This property is only available with query parameter provision_notify and cannot be set when creating new user accounts.

tfa_active
boolean

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

tfa_mail
string or null [ 1 .. 100 ] characters

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

tfa_phone
string or null [ 1 .. 40 ] characters

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

timezone
string or null [ 1 .. 100 ] characters

The time zone of the user, e.g. Australia/Sydney. Used for all profile settings with times, e.g. offtime and homework time schedules.

user_id
required
string [ 1 .. 50 ] characters

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

user_id_notify
string or null [ 1 .. 50 ] characters

The identifier of the user in the notification center.

user_id_oauth
string or null [ 1 .. 50 ] characters

The identifier of the user for authentication with OAuth2.

user_id_pdns
required
string [ 1 .. 40 ] characters

The identifier of the user in the notification center.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "password_hash": "string",
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Response samples

Content type
application/json
{
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "password_hash": "string",
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Return multiple existing user accounts.

Returns multiple existing user accounts.

Authorizations:
XApiKey
query Parameters
size
integer [ 1 .. 1000 ]
Default: 50

The size of a page to be returned from a result list (the maximum number of result elements to be returned from the entire list).

index
integer >= 0
Default: 0

The zero-based index of a page to be returned from a result list. If set to a positive integer, skips the specified number of pages in the result list. The size of a page will be determined with the query parameter size.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "index": 0,
  • "size": 0,
  • "total": 0,
  • "users": [
    ]
}

Return number of user accounts.

Returns the total number of existing user accounts in the database.

Authorizations:
XApiKey

Responses

Response samples

Content type
application/json
{
  • "count": 0
}