Mailbox API – Authentication and Authorization

Auth Methods

The Axigen Mailbox-API supports the following authentication and authorization methods:

OAuth 2.0 with OpenID Connect – for both browser based applications and mobile / native apps
Basic Authentication – in case OAuth 2.0 and OpenID Connect is not available
Cookie Authentication - for browser based clients

Note that using OAuth 2.0 and OpenID Connect is strongly recommended as it is the most secure option.

2-Step Verification and Catpcha are supported in the following scenarios:

when using OAuth 2.0 and OpenID Connect if enabled by the Authorization Server;
when using Cookie based authentication.

Request Headers

Name	Required	Values	Description
`Authorization`	*	`"Basic <username>:<password>", "Bearer <token>"`	“Basic” – used to authenticate against internal user authentication mechanism when OAuth 2.0 and OpenID Connect are not available “Bearer” – used to authenticate against an external authentication provider (such as OAuth 2.0 and OpenID Connect)

Name

Required

Values

Description

Authorization

"Basic <username>:<password>", "Bearer <token>"

“Basic” – used to authenticate against internal user authentication mechanism when OAuth 2.0 and OpenID Connect are not available

“Bearer” – used to authenticate against an external authentication provider (such as OAuth 2.0 and OpenID Connect)

Response

When successful, the endpoint returns the following JSON structure:

All subsequent API calls must use the same authentication method and include the session id in the X-Axigen-Session header.

Note that when using bearer token authorization, the username is unknown to Axigen until the token is validated against the external authentication provider.

In case the user can not be authenticated (i.e. wrong authentication credentials, invalid token, expired token, unknown user), the endpoint will reply back with 401 Unauthorized.

Cookie Login NEW

Request body (JSON)

Name	Type	Required	Description
`username`	`String`	*	The username including the domain name when the user does not belong to the primary domain or no primary domain is set
`password`	`String`	*	The account password
`captchaText`	`String`		The value of the captcha text
`captchaId`	`String`		The captcha id
`rememberLogin`	`Boolean`		The value set based on user choice

Response

When successful, the endpoint returns the following JSON structure:

Additionally, the response will also include the following headers when applicable:

Name	Type	Present	Values	Description
`Set-Cookie`	`String`	*		The Cookie to be used in all subsequent requests
`X-Axigen-2FA`	`String`		`required`, `mandatory`	The value is set to `required` when the a second step is required as part of the 2-Step Verification The value is set to `mandatory` when setting up 2-Step Verification must be performed before continuing

Name

Type

Present

Values

Description

Set-Cookie

String

The Cookie to be used in all subsequent requests

X-Axigen-2FA

String

required, mandatory

The value is set to required when the a second step is required as part of the 2-Step Verification

The value is set to mandatory when setting up 2-Step Verification must be performed before continuing

All subsequent API calls must use Cookie and include the session id as query parameter _h=<sessid>.

In case the user can not be authenticated (i.e. wrong authentication credentials, invalid captcha, unknown user), the endpoint will reply back with 401 Unauthorized.

Cookie Login with 2-Step Verification NEW

When 2-Step Verification is administratively enabled and active (i.e. the Cookie Login endpoint includes a X-Axigen-2FA header set to required), the API client must use this endpoint to complete the 2-Step Verification.

The API client should call the List Account Security Methods endpoint with scope=2fa to obtain the list of available methods. When using either an email or sms method, a totpToken must be obtained by calling Send Token.

Alternatively, a recoveryCode can be used to complete the 2-Step Verification. Recovery codes are generated automatically when activating the 2-Step Verification. They can also be regenerated by calling Regenerate Recovery Codes.

Request body (JSON)

Name	Type	Required	Description
`methodId`	`String`	*	The method id used for
`totpToken`	`String`	*	The TOTP code
`recoveryCode`	`String`	*	One of the recovery codes received when activating 2-Step Verification or after manually regenerating the recovery codes.

Either of methodId and totpToken or recoveryCode is required.

Response

If successful, the response will be empty.

Captcha NEW

This API is only available when using cookie login.

Get Status

Query parameters

Name	Type	Required	Values	Description
`username`	`String`	*		The username (including the domain name) for which the captcha requirement should be checked.

Response

When successful, the endpoint returns the following JSON structure:

Get Captcha

Query parameters

Name	Type	Required	Values	Description
`username`	`String`	*		The username (including the domain name) for which the captcha requirement should be checked.
`t`	`String`			Typically set to the current timestamp. This is used to work around browser level caching of the captcha image.

Response

When successful, the endpoint returns the captcha image as PNG in case captcha is required.

Additionally, the response will also include the following headers when applicable:

Name	Type	Present	Values	Description
`X-Captcha-Id`	`String`	*		The captcha id to be sent when calling cookie login.