Documentation Powered by ReDoc

${PRODUCT_NAME} - Provisioning API (1.0.0)

Download OpenAPI specification:Download

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

The provisioinng API of ${PRODUCT_NAME} 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.

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.

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

The email address used in the notification center (empty string: no email address registered). This property is only available with query parameter provision_notify.

mail_id
string

The identifier of the email address used in the notification center (empty string: no email address registered). This property is only available with query parameter provision_notify, and cannot be modified with a PATCH request.

password_hash
string [ 1 .. 100 ] characters

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

phone_2fa
string [ 1 .. 40 ] characters

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

phone_active
boolean

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

phone_id
string

The identifier of the phone number used in the notification center (empty string: no phone number registered). This property is only available with query parameter provision_notify, and cannot be modified with a PATCH request.

phone_number
string

The phone number used in the notification center (empty string: no phone number registered). 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.

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 [ 1 .. 50 ] characters

The identifier of the user in the notification center.

user_id_oauth
string [ 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
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_id": "string",
  • "password_hash": "string",
  • "phone_2fa": "string",
  • "phone_active": true,
  • "phone_id": "string",
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Response samples

Content type
application/json
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_id": "string",
  • "password_hash": "string",
  • "phone_2fa": "string",
  • "phone_active": true,
  • "phone_id": "string",
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "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
{ }

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
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_id": "string",
  • "password_hash": "string",
  • "phone_2fa": "string",
  • "phone_active": true,
  • "phone_id": "string",
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "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.

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.

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

The email address used in the notification center (empty string: no email address registered). This property is only available with query parameter provision_notify.

mail_id
string

The identifier of the email address used in the notification center (empty string: no email address registered). This property is only available with query parameter provision_notify, and cannot be modified with a PATCH request.

password_hash
string [ 1 .. 100 ] characters

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

phone_2fa
string [ 1 .. 40 ] characters

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

phone_active
boolean

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

phone_id
string

The identifier of the phone number used in the notification center (empty string: no phone number registered). This property is only available with query parameter provision_notify, and cannot be modified with a PATCH request.

phone_number
string

The phone number used in the notification center (empty string: no phone number registered). 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.

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 [ 1 .. 50 ] characters

The identifier of the user in the notification center.

user_id_oauth
string [ 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
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_id": "string",
  • "password_hash": "string",
  • "phone_2fa": "string",
  • "phone_active": true,
  • "phone_id": "string",
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "user_id": "string",
  • "user_id_notify": "string",
  • "user_id_oauth": "string",
  • "user_id_pdns": "string"
}

Response samples

Content type
application/json
{
  • "email_2fa": "string",
  • "has_2fa": true,
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_id": "string",
  • "password_hash": "string",
  • "phone_2fa": "string",
  • "phone_active": true,
  • "phone_id": "string",
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "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 with pagination support.

Authorizations:
XApiKey
query Parameters
skip
integer

If set to a positive integer, skips the specified number of users. Default value is 0 (start with first available user).

count
integer

If set to a positive integer, specifies the (maximum) number of users to be returned. Default value is 0 ( return all available users, taking parameter skipinto account).

Responses

Response samples

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