Mailbox API – Account Security | Axigen Documentation

This section is available starting with Axigen X6 (10.6).

Additional Security Check NEW

Check Password

This endpoint is not available when using OAuth 2.0.

To enhance security, accessing the Account Security features requires re-authentication. Users must re-enter their password, after which the API client must call the endpoint. This generates a securityToken that remains valid for a limited time.

All subsequent changes to security settings must include this securityToken in the request. If the token expires, API clients must call the endpoint to obtain a new one.

When 2-Step Verification is mandatory but not yet configured, a partially authorized session allows users to manage certain security features without a securityToken.

Request body (JSON)

Name	Type	Required	Values	Description
`password`	`String`	*		The account password

Response

Security Methods NEW

When using OAuth 2.0, multi factor authentication is provided by the Authorization server.

The admin can define the set of available security methods for each purpose (or scope) via the limits mechanism. This can be achieved either via WebAdmin or CLI and the status is reflected in the response of the Account Info endpoint, under securityPolicy as described below:

Allowing the activation of specific security methods by individually enabling alternateEmailAddress or phoneNumber.
Allowed 2-Step Verification methods reflected in the twoFactorAuthPolicy.methods .
Allowed Username Recovery methods reflected in the usernameRecoveryMethods.
Allowed Password Recovery methods reflected in the passwordRecoveryMethods.

List Methods

This endpoint returns the active security methods based on the requested scope.

Query parameters

Name	Type	Required	Values	Description
`scope`	`String`		"general", "2fa", "usernameRecovery", "passwordRecovery"	The purpose for which the security method should be used. Default value: "general"

Name

Type

Required

Values

Description

scope

String

"general", "2fa", "usernameRecovery", "passwordRecovery"

The purpose for which the security method should be used.

Default value: "general"

Response

Create Method

Requires a securityToken to be passed via the X-Axigen-Security-Token header, unless in

The security methods are not persisted until they are validated using the Activate Method endpoint. After a security method is created, it will be stored on the session pending activation.

Request body (JSON)

Name	Type	Required	Values	Description
`method`	`String`	*	“sms”, “email”, “authApp”	The type of communication channel
`target`	`String`	?		The phone number of email address. Required when method is “sms” or “email”

Response

Get QR

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

Available only for authApp methods.

URL parameters

Name	Type	Required	Description
`id`	`String`	true	The id of the method for which to retrieve the TOTP QR code.

Response

If successful, the response will return the QR code as SVG.

Send Token

Available only for sms and email methods.

URL parameters

Name	Type	Required	Description
`id`	`String`	true	The id of the method for which to send the TOTP code (sms or email).

Response

If successful, the response will be empty.

Activate Method

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

URL parameters

Name	Type	Required	Description
`id`	`String`	true	The id of the method to be activated.

Request body (JSON)

Name	Type	Required	Values	Description
`totpToken`	`String`	*		The TOTP code

Response

If successful, the response will be empty.

Revoke Method

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

URL parameters

Name	Type	Required	Description
`id`	`String`	true	The id of the method to be revoked.

Response

If successful, the response will be empty.

Revoke All Methods

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

Response

If successful, the response will be empty.

2-Step Verification NEW

Activate

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

Request body (JSON)

Name	Type	Required	Values	Description
`methodId`	`String`	*		The method id used to activate account-level 2FA
`totpToken`	`String`	*		The TOTP code

The activate 2FA Endpoint will return a list of recovery codes. A recovery code can be used for login as an alternative to an account security method.

Response

Deactivate

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

Request body (JSON)

Name	Type	Required	Values	Description
`methodId`	`String`	*		The method id used to activate account-level 2FA
`totpToken`	`String`	*		The TOTP code

Response

If successful, the response will be empty.

Regenerate Recovery Codes

Requires a securityToken to be passed via the X-Axigen-Security-Token header.

This endpoint will regenerate the list o recovery codes. Previously generated recovery codes will no longer be usable.

Response

Username Recovery NEW

Public endpoint

Request body (JSON)

Name	Type	Required	Values	Description
`email`	`String`	*		The recovery email address
`phoneNumber`	`String`	*		The recovery phone number

One of email or phoneNumber is required.

Response

The response will always be successful.

Password Recovery NEW

List Available Methods

Public endpoint

This endpoint returns a list of available recovery methods based on the account limits.

URL parameters

Name	Type	Required	Description
`username`	`String`	true	The id of the method for which to retrieve the TOTP QR code.

Response

Send Recovery Token via Selected Method

Public endpoint

Request body (JSON)

Name	Type	Required	Description
`username`	`String`	*	The username for which password recovery is attempted
`email`	`String`	*	The recovery email address
`phoneNumber`	`String`	*	The recovery phone number

One of email or phoneNumber is required.

Response

If successful, the response will be 200 OK.

Validate Token

Public endpoint.

Calling this endpoint is optional. The reset password endpoint could be called directly and it is up to the Mailbox API client if the validate token endpoint is called before showing the reset password interface.

Request body (JSON)

Name	Type	Required	Values	Description
`username`	`String`	*		The username for which password recovery is attempted
`recoveryToken`	`String`	*		The recovery token received via the email or sms

Response

If successful, the response will be 200 OK.

The response will also include the active password policy.

Reset Password

Public endpoint.

This endpoint needs the recoveryToken received by the user via email or sms.

Request body (JSON)

Name	Type	Required	Description
`userName`	`String`	*	The recovery email address
`recoveryToken`	`String`	*	The recovery token retrieved by Send Recovery Token Api
`newPassword`	`String`	*	The new password

Response

If successful, the response will be 200 OK.

If the reset fails due to the password policy, the response will include the following details in the JSON response: