User API

Overview

User API is a REST API for managing Fess user accounts. You can create, get, update, and delete users, and assign roles and groups.

This is an admin API, and access requires authentication with an admin access token. See Admin API Overview for the authentication method and common specifications.

Every response is wrapped in a response object and includes the following common fields:

  • version : The Fess product version string.

  • status : The result status code (0 =success, 1 =bad request, 2 =system error, 3 =unauthorized, 9 =failed).

Base URL

/api/admin/user

Endpoint List

Method Path Description
GET /settings List users
GET /setting/{id} Get user
POST /setting Create user
PUT /setting Update user
DELETE /setting/{id} Delete user

List Users

Request

GET /api/admin/user/settings

Parameters

Parameter Type Required Description
size Integer No Number of items per page. The default is the configured value paging.page.size (default: 25).
page Integer No Page number (starts from 1). The default is 1.

Note

In the current implementation, the user list endpoint does not apply the size and page parameters. It always returns the first page, with the number of items defined by the server setting paging.page.size (default: 25), sorted by username (name) in ascending order. The total number of matching users is available in response.total.

Response

{
  "response": {
    "version": "15.9",
    "status": 0,
    "settings": [
      {
        "id": "YWRtaW4=",
        "name": "admin",
        "attributes": {
          "surname": "Administrator",
          "givenName": "System",
          "mail": "admin@example.com"
        },
        "roles": ["YWRtaW4=", "Z3Vlc3Q="],
        "groups": [],
        "version_no": 1
      }
    ],
    "total": 10
  }
}

  • settings : The array of users on the current page.

  • total : The total number of matching users.

Get User

Request

GET /api/admin/user/setting/{id}

Specify the document ID of the target user in {id}.

Response

{
  "response": {
    "version": "15.9",
    "status": 0,
    "setting": {
      "id": "YWRtaW4=",
      "name": "admin",
      "attributes": {
        "surname": "Administrator",
        "givenName": "System",
        "mail": "admin@example.com",
        "telephoneNumber": "",
        "uidNumber": "",
        "gidNumber": "",
        "homeDirectory": ""
      },
      "roles": ["YWRtaW4=", "Z3Vlc3Q="],
      "groups": [],
      "version_no": 1
    }
  }
}

Note

attributes includes all attributes stored for the user, except name, password, roles, and groups. password is not included in the response.

Create User

Request

POST /api/admin/user/setting
Content-Type: application/json

Request Body

{
  "name": "testuser",
  "password": "securepassword",
  "confirm_password": "securepassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User",
    "mail": "testuser@example.com"
  },
  "roles": ["Z3Vlc3Q="],
  "groups": ["group_id_1"]
}

Field Description

Field Required Description
name Yes Username (login ID)
password Yes Password
confirm_password No Confirmation password
attributes No Map of attributes (see below)
roles No Array of role IDs
groups No Array of group IDs

Note

Give the ID of a role or group in roles and groups, not its name. An ID that does not exist (including a role or group name) is rejected with 400. You can find the IDs in the id returned by GET /api/admin/role/settings and GET /api/admin/group/settings. The ID of a role or group created in the admin UI or through the API is its name encoded as Base64 URL (for example, YWRtaW4= for the built-in role admin and Z3Vlc3Q= for guest).

Note

The same password checks as in the admin UI apply. A create request without password, a confirm_password that differs from password (confirm_password itself may be omitted), and a password that breaks the password policy (password.min.length (default 8), password.max.length, password.require.* and password.invalid.admin.passwords in fess_config.properties) are all rejected with 400.

The keys of attributes are the user entity attribute names (the schema item names derived from LDAP). The most common keys are:

  • surname, givenName, displayName, mail

  • telephoneNumber, mobile, homePhone

  • employeeNumber, title, description, homeDirectory

  • uidNumber, gidNumber

uidNumber and gidNumber must be numeric (their type is validated on update). Many other LDAP attribute keys can also be specified.

Note

On creation, the user ID (document ID) is automatically generated as the Base64 URL-encoded value of the username (for example, the username admin becomes YWRtaW4=).

Response

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "new_user_id",
    "created": true
  }
}

  • id : The document ID of the created user.

  • created : true when created.

Update User

Request

PUT /api/admin/user/setting
Content-Type: application/json

Request Body

{
  "id": "existing_user_id",
  "name": "testuser",
  "password": "newpassword",
  "confirm_password": "newpassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User Updated",
    "mail": "testuser.updated@example.com"
  },
  "roles": ["Z3Vlc3Q=", "YWRtaW4="],
  "groups": ["group_id_1", "group_id_2"],
  "version_no": 1
}

Field Description

Field Required Description
id Yes The document ID of the user to update.
name Yes Username (login ID)
version_no Yes Version number (for optimistic locking)
password No New password (updated only when specified)
confirm_password No Confirmation password
attributes No Map of attributes (see “Create User”)
roles No Array of role IDs
groups No Array of group IDs

Note

On update, id, name, and version_no are required. version_no is the value returned when getting the target user (GET), and it corresponds to the OpenSearch document version. If it does not match the current version, the request is treated as a conflict and the update is rejected.

Response

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "existing_user_id",
    "created": false
  }
}

  • created : false for an update.

Delete User

Request

DELETE /api/admin/user/setting/{id}

Specify the document ID of the user to delete in {id}.

Note

You cannot delete the currently logged-in user.

Response

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "deleted_user_id",
    "created": false
  }
}

  • id : The document ID of the deleted user.

Usage Examples

Create New User

curl -X POST "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "john.doe",
       "password": "SecureP@ss123",
       "confirm_password": "SecureP@ss123",
       "attributes": {
         "surname": "Doe",
         "givenName": "John",
         "mail": "john.doe@example.com"
       },
       "roles": ["Z3Vlc3Q="],
       "groups": []
     }'

Change User Roles

curl -X PUT "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "user_id_123",
       "name": "john.doe",
       "roles": ["Z3Vlc3Q=", "YWRtaW4="],
       "version_no": 1
     }'

Reference