Authentication / Session API

Overview

The v2 API uses session-based authentication. Log in via POST /auth/login; on success, a session is established and a CSRF token is issued.

State-changing requests (POST) require the X-Fess-CSRF-Token header. For information on how to obtain and rotate CSRF tokens, as well as the common response envelope and error model, see API Overview.

This page describes the following four endpoints:

Endpoint List
Endpoint Method Description
/auth/me GET Retrieves the currently authenticated user.
/auth/login POST Logs in with a username and password.
/auth/logout POST Logs out (idempotent).
/auth/password POST Changes the current user’s password.

Common User Information (UserPayload)

User information included in the responses of GET /auth/me and POST /auth/login is returned in the common UserPayload structure. All array fields are non-null; an empty array is returned when there are no values.

UserPayload
Field Type Description
user_id string User ID. (Required)
username string Display username for the SPA account menu. Currently the same value as user_id, but may be provided independently by the backend in the future. (Required)
name string Display name for the SPA account menu. Currently the same value as user_id. (Required)
roles string[] Array of user roles. (Required)
groups string[] Array of user groups. (Required)
permissions string[] Array of user permissions. (Required)
editable boolean Whether the user information is editable. (Required)
admin boolean true when the user has any of the configured authentication.admin.roles. Controls the display of the “Administration” item in the SPA. (Required)

Fetching Authentication State

Request

HTTP Method GET
Endpoint /api/v2/auth/me

Retrieves the currently authenticated user. An anonymous call does not result in an error; it returns authenticated: false. When authenticated, user holds the UserPayload.

Response

On success (HTTP 200), the following response is returned in the common envelope format (example for authenticated user).

{
  "response": {
    "status": 0,
    "authenticated": true,
    "user": {
      "user_id": "taro",
      "username": "taro",
      "name": "taro",
      "roles": ["admin"],
      "groups": [],
      "permissions": ["1taro"],
      "editable": true,
      "admin": true
    }
  }
}

Each element of response is as follows:

Response Information
Field Type Description
authenticated boolean Whether authenticated. (Required)
user object UserPayload. Present only when authenticated is true.

Error Response

Error Response
Status Code Description
405 Method Not Allowed An unsupported HTTP method was specified.
500 Internal Server Error An internal server error occurred.

Login

Request

HTTP Method POST
Endpoint /api/v2/auth/login

Logs in with a username and password. On successful login, the servlet session ID is rotated, a new CSRF token is issued, and the rate-limit buckets for the caller’s IP and the target user are cleared.

Rate limiting is applied along two axes: per caller IP and per user. When the per-IP limit is exceeded, 429 Too Many Requests is returned together with a Retry-After header (in seconds). When the per-user limit is exceeded, the same 401 Unauthorized as for invalid credentials is returned (without a Retry-After header), so that the state of the counter cannot be inferred from outside.

Even if a session is already authenticated, no short-circuit occurs; the provided credentials are always validated.

return_to must be a relative path matching ^/[A-Za-z0-9_\-/.?&=%:@+~#*!,;]*$. Additionally, protocol-relative paths (starting with //) and paths containing ASCII control characters are rejected and silently removed from the echoed response.

Note

This endpoint is exempt from CSRF validation (because no token exists before login).

Note

Unlike other state-changing endpoints, this endpoint consolidates oversized request bodies and unsupported Content-Type into 400 invalid_request (other endpoints return 413 / 415).

Note

The rate limits for login and password change can be configured with the following properties (defaults in parentheses):

  • theme.api.login.rate.limit.per.ip.per.minute (10): Maximum number of attempts per minute per IP address. Applies only to /auth/login.

  • theme.api.login.rate.limit.per.user.per.minute (5): Maximum number of attempts per minute per user. Applies to both /auth/login and /auth/password.

  • theme.api.login.lockout.seconds (900): Lockout duration (in seconds) after the limit is exceeded. Returned as the value of the Retry-After header.

Request Body (LoginRequest)

Content-Type is application/json (charset UTF-8). The maximum request body size is 4 KiB.

LoginRequest
Field Type Required Description
username string Yes Username. minLength is 1.
password string Yes Password. minLength is 1.
return_to string No Redirect destination after login. Must be a relative path matching the pattern above.

Request example:

{
  "username": "taro",
  "password": "secret",
  "return_to": "/search"
}

Response

On success (HTTP 200, LoginResponse), the following response is returned in the common envelope format.

{
  "response": {
    "status": 0,
    "user": {
      "user_id": "taro",
      "username": "taro",
      "name": "taro",
      "roles": ["admin"],
      "groups": [],
      "permissions": ["1taro"],
      "editable": true,
      "admin": true
    },
    "csrf_token": "0c1f2e3d4a5b6c7d8e9f",
    "return_to": "/search"
  }
}

Each element of response is as follows:

Response Information
Field Type Description
user object UserPayload.
csrf_token string New CSRF token associated with the new session. (Required)
return_to string Echoed only if the request value passed the allowlist.

Error Response

Error Response
Status Code Description
400 Bad Request The request is invalid (including oversized request body or unsupported Content-Type).
401 Unauthorized The credentials are invalid.
405 Method Not Allowed An unsupported HTTP method was specified.
429 Too Many Requests The rate limit was exceeded. The Retry-After header indicates the number of seconds to wait.
500 Internal Server Error An internal server error occurred.

Logout

Request

HTTP Method POST
Endpoint /api/v2/auth/logout

Logs out. This operation is idempotent; if there is no active session, it is a no-op and does not return an error. Always returns ok: true.

The X-Fess-CSRF-Token header is required.

Response

On success (HTTP 200, OkResponse), the following response is returned in the common envelope format.

{
  "response": {
    "status": 0,
    "ok": true
  }
}

Each element of response is as follows:

Response Information
Field Type Description
ok boolean Always true. (Required)

Error Response

Error Response
Status Code Description
403 Forbidden The CSRF token is missing or expired.
405 Method Not Allowed A method other than POST was specified. The Allow: POST header is included.
500 Internal Server Error An internal server error occurred.

Password Change

Request

HTTP Method POST
Endpoint /api/v2/auth/password

Changes the current user’s password. Validates current_password, applies the configured password policy to new_password, invalidates the current session, and returns re_login_required: true to prompt the SPA to redirect to the login page.

Since the session is destroyed server-side, csrf_token is not returned. The SPA must obtain a new token after re-authentication.

The X-Fess-CSRF-Token header is required.

A per-user rate limit is applied to this endpoint; when the limit is exceeded, 429 Too Many Requests is returned together with a Retry-After header (the settings are shared with login).

Request Body (PasswordChangeRequest)

Content-Type is application/json (charset UTF-8). The maximum request body size is 4 KiB.

PasswordChangeRequest
Field Type Required Description
current_password string Yes Current password. minLength is 1.
new_password string Yes New password. Must satisfy the configured password policy (minimum 8 characters by default). minLength is 1.
confirm_password string Yes Confirmation password. Must match new_password. minLength is 1.

Response

On success (HTTP 200), the following response is returned in the common envelope format.

{
  "response": {
    "status": 0,
    "ok": true,
    "re_login_required": true
  }
}

Each element of response is as follows:

Response Information
Field Type Description
ok boolean Always true. (Required)
re_login_required boolean Always true. The current session has been invalidated server-side. The SPA must redirect to the login page to obtain a new session and CSRF token. (Required)

Error Response

Error Response
Status Code Description
400 Bad Request The request is invalid.
401 Unauthorized Authentication is required, or current_password is invalid.
403 Forbidden The CSRF token is missing or expired.
405 Method Not Allowed An unsupported HTTP method was specified.
413 Payload Too Large The request body exceeds the size limit.
415 Unsupported Media Type The Content-Type is not supported.
429 Too Many Requests The rate limit was exceeded.
500 Internal Server Error An internal server error occurred.