Auth Services

Web services support two authentication methods:

  1. Session-based authentication

  2. API key authentication

Session-based authentication

Session-based authentication requires the client application to keep track of session ID and cookies between requests.

The session can be established with login services:

Login

Request
POST /callback HTTP/1.1
Header
Content-Type: application/json
Body
{
  "username": "admin",
  "password" : "secret"
}

The authentication data is sent in the body of the request.

Returns response with HTTP status 200 if login success otherwise returns HTTP status 401.

Only relevant headers and request body is shown.

Logout

Request
GET /logout HTTP/1.1

The login response returns session cookies which should be tracked by client application.

Some libraries that can keep track of sessions:

API key authentication

API key authentication allows clients to authenticate API requests without maintaining a session. This is particularly useful for server-to-server communication and automated scripts.

Managing API keys

API keys are managed by the com.axelor.auth.db.UserToken object. Each user can have multiple API keys with different names and expiration dates.

Creating API keys

API keys can be created from the User Preference form. To create a new API key:

  1. Checkout "Manage API key?"

  2. Click "Add" to create a new API key

  3. Provide a name

  4. Set an expiration date (default is one month from creation)

  5. Click "Create API key"

When a new API key is created, it will be displayed only once. Make sure to copy and store it securely as you won’t be able to view it again later.

Managing existing API keys

The API Keys tab displays a list of all tokens for the user with the following information:

  • Name: A descriptive name for the token

  • Expiration date: When the token will expire

  • Last used: The last time the token was used for authentication

The system provides visual indicators for token expiration: * Red highlight: For expired tokens * Yellow highlight: For tokens expiring within 7 days

Token operations

For each token, you can perform the following operations:

  • Revoke: Permanently disables the token. Any services using this token will immediately lose access.

  • Rotate: Replaces the token with a new one while maintaining the same name and expiration date. This is useful when you suspect a token might have been compromised.

API keys should be treated as sensitive information. Do not share your API keys and store them securely.

Using API keys for authentication

To authenticate using an API key, include the API key in the API-KEY HTTP header with each request:

Request with API Key Authentication
GET /ws/path
Header
API-KEY: <your-api-key>

The API key authentication does not create a session, so each request must include the API-KEY header.

API key validation

All API requests are authenticated through the following security checks:

  1. Key validation

    • Verifies the structure and presence of the API key

    • Authenticates the key against stored credentials

  2. Validity checks

    • Checks if the API key hasn’t expired

    • Confirms the associated user account is active

If any of these checks fail, the request is rejected with HTTP status 401 Unauthorized.

Multi-Factor Authentication (MFA)

Multi-Factor Authentication (MFA) is an optional feature that enhances account security by requiring users to verify their identity using a second factor in addition to their password.

Supported MFA methods

The following MFA methods are supported :

  • TOTP (Time-based One-Time Password): A 6-digit code generated by an authenticator app (e.g., Google Authenticator). The code refreshes every 30 seconds and is valid only during that short window.

  • Email verification: A 6-digit code sent to the user’s registered email address. The code is typically valid for 5 minutes.

  • Recovery codes: A set of 10 backup codes that can be used when primary MFA methods are unavailable.

Users can enable either method based on their preference.

Managing MFA configuration

MFA settings are managed through the MFA Configuration form in user preferences.

Each user can:

  • Choose their preferred MFA method: Select between the two supported methods (TOTP or Email).

  • Generate recovery codes: After enabling MFA, a set of 10 recovery codes is generated automatically.

  • Configure and test the setup before enabling it: Before activating MFA, users are guided through a setup process to register their chosen method and confirm that it’s working correctly by entering a test code.

  • Set a default MFA method: users can designate the default MFA method by clicking the star button next to it. This method will then be used during login.

  • Enable/Disable MFA:MFA is optional and can be turned on or off from the settings page.

Users must validate the configuration before it becomes active and ready to use as the default second authentication method.

MFA verification flow

Once MFA is enabled, the authentication process follows these steps:

  1. The user enters their valid username and password.

  2. If MFA is active:

    • For TOTP: The user is prompted to enter the current code from their authenticator app.

    • For Email: A verification code is automatically sent to their registered email.

    • For Recovery: The user can enter a recovery code if other methods are unavailable.

  3. Access is granted only after successful verification.