${PRODUCT_NAME} - Provisioning API (1.0.0)

Download OpenAPI specification:Download

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.

put /user
/$href(/provisioning/v1)/user

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

Authorizations:
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:
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

200

User account created successfully.

400

Malformed request body data.

401

Unauthorized (missing or wrong API token).

500

Unexpected error (internal server error).

Request samples

Copy
Expand all Collapse all
{
  • "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

application/json
Copy
Expand all Collapse all
{
  • "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.

delete /user/{user_id}
/$href(/provisioning/v1)/user/{user_id}

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

Authorizations:
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

200

User account found and deleted successfully.

204

Nothing to delete (user account does not exist).

401

Unauthorized (missing or wrong API token).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
Expand all Collapse all
{ }

Return an existing user account.

get /user/{user_id}
/$href(/provisioning/v1)/user/{user_id}

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

Authorizations:
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

200

User account found and returned successfully.

401

Unauthorized (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",
  • "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.

patch /user/{user_id}
/$href(/provisioning/v1)/user/{user_id}

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

Authorizations:
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:
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

200

User account updated successfully.

400

Malformed request body data.

401

Unauthorized (missing or wrong API token).

404

User does not exist (wrong user identifier in URL). This status will also be returned, if the provision flags have been used, but the accounts have not been found in either the PowerDNS platform or in the notification center.

500

Unexpected error (internal server error).

Request samples

Copy
Expand all Collapse all
{
  • "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

application/json
Copy
Expand all Collapse all
{
  • "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.

get /users
/$href(/provisioning/v1)/users

Returns multiple existing user accounts with pagination support.

Authorizations:
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

200

User accounts found and returned successfully.

401

Unauthorized (missing or wrong API token).

500

Unexpected error (internal server error).

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "index": 0,
  • "users":
    [
    ]
}