Skip to main content
The Users API lets you create, retrieve, update, and delete Redmine user accounts.
Most Users API endpoints require administrator privileges. The only exception is GET /users/:id.json, which any authenticated user can call for visible users.

​
Endpoints

MethodPathDescriptionAdmin required
GET/users.jsonList users.Yes
GET/users/:id.jsonGet a single user.No
POST/users.jsonCreate a user.Yes
PUT/users/:id.jsonUpdate a user.Yes
DELETE/users/:id.jsonDelete a user.Yes

​
List users

GET /users.json Returns a paginated list of all users. Requires administrator access.

​
Query parameters

​
status
number
default:"1"
Filter by user status. 0 = anonymous, 1 = active, 2 = registered (not yet activated), 3 = locked.
​
name
string
Filter users whose login, firstname, lastname, or email contains this string.
​
group_id
number
Filter users who are members of this group.
​
offset
number
default:"0"
Number of records to skip.
​
limit
number
default:"25"
Number of records per page (max 100).

​
Example

curl -H "X-Redmine-API-Key: ADMIN_API_KEY" \
  "https://redmine.example.com/users.json?status=1&limit=50"

​
Response

{
  "users": [
    {
      "id": 3,
      "login": "jsmith",
      "firstname": "Jane",
      "lastname": "Smith",
      "mail": "jsmith@example.com",
      "created_on": "2024-01-10T08:00:00Z",
      "updated_on": "2024-03-01T12:00:00Z",
      "last_login_on": "2024-03-20T09:30:00Z",
      "status": 1
    }
  ],
  "total_count": 1,
  "offset": 0,
  "limit": 25
}

​
Get user

GET /users/:id.json Returns a single user. Use current as the ID to get the authenticated user’s profile.

​
Path parameters

​
id
string
required
The numeric user ID, or current for the authenticated user.

​
Query parameters

​
include
string
Comma-separated list of associations to embed. Valid values: memberships, groups.

​
Examples

# Get a specific user (admin only for full details)
curl -H "X-Redmine-API-Key: ADMIN_API_KEY" \
  "https://redmine.example.com/users/3.json?include=memberships,groups"

# Get the currently authenticated user
curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  https://redmine.example.com/users/current.json

​
Response fields

​
user
object
required

​
Create user

POST /users.json Creates a new user account. Requires administrator access.

​
Request body

Wrap all fields inside a user object.
​
user.login
string
required
Username. Max 60 characters. Alphanumeric, -, _, @, and . only.
​
user.firstname
string
required
First name. Max 30 characters.
​
user.lastname
string
required
Last name. Max 255 characters.
​
user.mail
string
required
Email address.
​
user.password
string
Password. Required unless generate_password is true or an auth_source_id is specified.
​
user.password_confirmation
string
Password confirmation. Must match password.
​
user.generate_password
boolean
default:"false"
When true, Redmine generates a random password and sends it to the user by email.
​
user.auth_source_id
number
ID of an LDAP authentication source. When set, the password is managed by LDAP.
​
user.admin
boolean
default:"false"
Grant administrator privileges.
​
user.mail_notification
string
default:"only_my_events"
Email notification setting. One of: all, selected, only_my_events, only_assigned, only_owner, only_my_watches, none.
​
user.must_change_passwd
boolean
default:"false"
Force the user to change their password on next login.
​
user.custom_fields
object[]
Array of custom field values: [{"id": 1, "value": "value"}].

​
Example

curl -X POST \
  -H "X-Redmine-API-Key: ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "login": "jdoe",
      "firstname": "John",
      "lastname": "Doe",
      "mail": "jdoe@example.com",
      "password": "s3cur3P@ss",
      "password_confirmation": "s3cur3P@ss",
      "mail_notification": "only_my_events"
    }
  }' \
  https://redmine.example.com/users.json
A successful response returns 201 Created with the new user in the body.

​
Update user

PUT /users/:id.json Updates an existing user account. Requires administrator access.

​
Path parameters

​
id
number
required
The numeric ID of the user to update.

​
Example

curl -X PUT \
  -H "X-Redmine-API-Key: ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "firstname": "Jonathan",
      "mail_notification": "all",
      "must_change_passwd": true
    }
  }' \
  https://redmine.example.com/users/3.json
A successful response returns 200 OK.

​
Delete user

DELETE /users/:id.json Deletes a user account. Requires administrator access.
Deleting a user is irreversible. Issues, time entries, and journal entries authored by this user are preserved but will show a deleted user.

​
Path parameters

​
id
number
required
The numeric ID of the user to delete.

​
Example

curl -X DELETE \
  -H "X-Redmine-API-Key: ADMIN_API_KEY" \
  https://redmine.example.com/users/3.json
A successful response returns 200 OK.