Mailbox API – Authentication and Authorization

The Axigen Mailbox API requires every request to be made in the context of an authenticated session. This page describes the ways a client can obtain a session, how to carry it on subsequent requests, and the additional steps that may be required before a session becomes usable.

Auth Methods

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

Choosing a Method

• If your deployment already has an external identity provider, use External OAuth 2.0 with OpenID Connect. Your application obtains a token from the provider and Axigen validates it.

• If there is no external provider and you are building a mobile or native app that should keep the user signed in, use Axigen OAuth 2.0. Axigen itself issues an access and refresh token pair.

• Use Cookie Authentication for browser based clients, and Basic Authentication only when neither OAuth option is available.

Sessions

Every method ends with a session identifier (sessid). Each subsequent request must carry two things: the session identifier, and the credential the session was created with.

The session identifier travels in the X-Axigen-Session header, whichever login endpoint produced it:

The credential depends on how the session was created, and is not interchangeable:

Behind the webmail proxy, the session identifier is returned with a 32 character backend routing suffix appended. Send the value exactly as received – only the leading 32 characters are used.

2-Step Verification and Captcha

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

Login

Request Headers

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.

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

Cookie Login

Request body (JSON)

Response

When successful, the endpoint returns the following JSON structure:

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

All subsequent API calls must send the _hmail cookie and include the session ID in the X-Axigen-Session header.

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

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)

Response

If successful, the response will be empty.

Password Expiration 10.7+

When logging in with a password that has expired (i.e. the login endpoint includes a X-Axigen-Expired-Password header set to true), the API client must use the password reset endpoint in order to change the password before doing anything else. They can check the password policy details using the account info endpoint. This happens after the 2-Step Verification, if it is configured.

Captcha

This API is only available when using cookie login.

Get Status

Query parameters

Response

When successful, the endpoint returns the following JSON structure:

Get Captcha

Query parameters

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:

Axigen OAuth 2.0 10.7+

Axigen can act as its own OAuth 2.0 authorization server, issuing access and refresh tokens for registered first party clients. This lets an application keep a user signed in without storing their password and without an external identity provider.

The flow differs from a classic third party OAuth 2.0 authorization: rather than redirecting the user to a consent screen, the client starts from an already authenticated session and exchanges it for a durable token pair. Use one of the session login methods described above to obtain that initial session.

Flow Overview

1. Sign the user in with a session login method to obtain a session.

2. Call POST /api/v1/login/code from that session to obtain a short lived authorization code. This ends the session.

3. Exchange the code for an access and refresh token pair at POST /api/v1/auth/token. No session is required for this call.

4. Call POST /api/v1/session with the access token to obtain a session.

5. When the access token expires, obtain a fresh pair at POST /api/v1/auth/token using the refresh token, then repeat step 4.

6. On logout, revoke the refresh token with POST /api/v1/auth/revoke.

PKCE

Every authorization code is bound to a PKCE verifier (RFC 7636). Before requesting a code, generate a random code_verifier of 43 to 128 characters from [A-Za-z0-9-._~] and derive the challenge as BASE64URL(SHA256(code_verifier)). Send the challenge to /api/v1/login/code and the original verifier to /api/v1/auth/token.

Only the S256 method is supported. plain is rejected.

Token Lifetimes

Registered Clients

Client registration is static. The redirectUri presented on a request must match the registered value for that clientId exactly.

Request an Authorization Code

Requires an authenticated session. Consumes it.

Request body (JSON)

Response

When successful, the endpoint returns the following JSON structure:

The redirect URL is the registered redirectUri with the authorization code and your state appended as percent encoded query parameters, for example axigen://auth?code=<code>&state=<state>. Confirm the returned state matches the one you sent before using the code.

The response also expires the _hmail session cookie.

Errors

Exchange the Code for Tokens

Public endpoint – no session or prior authentication required. The request body must be application/x-www-form-urlencoded; any other content type is rejected.

Request body (application/x-www-form-urlencoded)

Response

When successful, the endpoint returns the following JSON structure:

Responses carry Cache-Control: no-store.

Refresh the Token Pair

Public endpoint. Same endpoint as the code exchange, distinguished by grant_type.

Request body (application/x-www-form-urlencoded)

Response

Identical in shape to the code exchange response.

Refresh tokens are rotated: each refresh returns a new pair and invalidates the token presented. Persist the new refresh token before using it, and discard the old one.

Open a Session

Exchanges a valid access token for a Mailbox API session. No request body.

Request Headers

Response

When successful, the endpoint returns the following JSON structure:

Additionally, the response will also include the following header

All subsequent API calls must send the _hmail cookie and include the session ID in the X-Axigen-Session header.

Sessions created this way are treated as having completed 2-Step Verification – it was completed during the sign in that produced the authorization code.

Errors

401 Unauthorized with a WWW-Authenticate: Bearer header and an OAuth 2.0 error body. error is invalid_token when the token is missing, malformed, unverifiable, refers to an unknown user, or predates a password change or session invalidation; invalid_request when a session cookie is present; server_error when session creation fails.

Revoke a Refresh Token

Public endpoint, per RFC 7009. Call this on logout. The request body must be application/x-www-form-urlencoded.

Request body (application/x-www-form-urlencoded)

Response

If successful, the response will be empty, with 200 OK.

Verify Token Signatures

Public endpoint. Returns the public keys used to verify Axigen issued tokens, allowing a client or resource server to check them offline.

Response

When successful, the endpoint returns the following JSON structure:

Keys are derived per 60 day period, and the set covers the previous, current and next period. Cache the key set and refetch it when a token presents an unknown kid. Tokens without a kid, or with a kid outside the accepted set, are rejected.

Error Responses

/api/v1/auth/token and /api/v1/auth/revoke return RFC 6749 error bodies rather than the standard Mailbox API error envelope: