Project

General

Profile

Rest Users » History » Version 30

Lorenzo Meneghetti, 2023-12-08 20:32

1 1 Jean-Philippe Lang
h1. Users
2
3 3 Jean-Philippe Lang
{{>toc}}
4
5 7 Jean-Philippe Lang
h2. /users.:format
6 1 Jean-Philippe Lang
7 7 Jean-Philippe Lang
h3. GET
8
9
Returns a list of users.
10
11 20 Cyril Jouve
This endpoint requires admin privileges.
12
13 7 Jean-Philippe Lang
+Example+:
14
15 1 Jean-Philippe Lang
  GET /users.xml
16
17 10 Jean-Baptiste Barth
Optional filters:
18
19 25 Martin von Wittich
* @status@: get only users with the given status. See "app/models/principal.rb":/projects/redmine/repository/entry/trunk/app/models/principal.rb#L22-25 for a list of available statuses. Supply an empty value to match all users regardless of their status. Default is @1@ (active users). Possible values are:
20 13 Go MAEDA
** @1@: Active (User can login and use their account)
21
** @2@: Registered (User has registered but not yet confirmed their email address or was not yet activated by an administrator. User can not login)
22
** @3@: Locked (User was once active and is now locked, User can not login)
23 10 Jean-Baptiste Barth
* @name@: filter users on their login, firstname, lastname and mail ; if the pattern contains a space, it will also return users whose firstname match the first word or lastname match the second word.
24
* @group_id@: get only users who are members of the given group
25
26 7 Jean-Philippe Lang
h3. POST
27 1 Jean-Philippe Lang
28 7 Jean-Philippe Lang
Creates a user.
29 1 Jean-Philippe Lang
30 20 Cyril Jouve
This endpoint requires admin privileges.
31
32 7 Jean-Philippe Lang
+Parameters+:
33 1 Jean-Philippe Lang
34 7 Jean-Philippe Lang
* @user@ (required): a hash of the user attributes, including:
35 1 Jean-Philippe Lang
36 7 Jean-Philippe Lang
  * @login@ (required): the user login
37
  * @password@: the user password
38
  * @firstname@ (required)
39
  * @lastname@ (required)
40
  * @mail@ (required)
41
  * @auth_source_id@: authentication mode id
42 12 Matt Wiseley
  * @mail_notification@: only_my_events, none, etc.
43
  * @must_change_passwd@: true or false
44 19 F. P.
  * @generate_password@: true or false
45 29 Lorenzo Meneghetti
  * @custom_fields@ - See [[Rest_api#Working-with-custom-fields|Custom fields]]
46 28 Lorenzo Meneghetti
* @send_information@: true or false : Send account information to the user
47 19 F. P.
48 1 Jean-Philippe Lang
49 7 Jean-Philippe Lang
+Example+:
50 1 Jean-Philippe Lang
51 17 Toshi MARUYAMA
<pre>
52 7 Jean-Philippe Lang
POST /users.xml
53 17 Toshi MARUYAMA
</pre>
54 1 Jean-Philippe Lang
55 16 Toshi MARUYAMA
<pre><code class="xml">
56 7 Jean-Philippe Lang
<?xml version="1.0" encoding="ISO-8859-1" ?>
57
<user>
58
  <login>jplang</login>
59
  <firstname>Jean-Philippe</firstname>
60
  <lastname>Lang</lastname>
61
  <password>secret</password>
62
  <mail>jp_lang@yahoo.fr</mail>
63
  <auth_source_id>2</auth_source_id>
64
</user>
65 16 Toshi MARUYAMA
</code></pre>
66 7 Jean-Philippe Lang
67 8 Lutz Horn
JSON
68
69 16 Toshi MARUYAMA
<pre><code class="json">
70 8 Lutz Horn
{
71
    "user": {
72
        "login": "jplang",
73
        "firstname": "Jean-Philippe",
74
        "lastname": "Lang",
75
        "mail": "jp_lang@yahoo.fr",
76
        "password": "secret"
77
    }
78
}
79 16 Toshi MARUYAMA
</code></pre>
80 8 Lutz Horn
81 7 Jean-Philippe Lang
+Response+:
82
83
  * @201 Created@: user was created
84
  * @422 Unprocessable Entity@: user was not created due to validation failures (response body contains the error messages)
85
86
h2. /users/:id.:format
87
88
h3. GET
89
90
Returns the user details. You can use @/users/current.:format@ for retrieving the user whose credentials are used to access the API.
91
92 21 Cyril Jouve
This endpoint can be used by admin or non admin but the returned fields will depend on the privileges of the requesting user (see Response below).
93 20 Cyril Jouve
94 3 Jean-Philippe Lang
+Parameters+:
95 1 Jean-Philippe Lang
96 23 Go MAEDA
* @include@ (optional): a comma separated list of associations to include in the response:
97 1 Jean-Philippe Lang
98 11 Jean-Baptiste Barth
  * @memberships@ : adds extra information about user's memberships and roles on the projects
99
  * @groups@ (added in 2.1) : adds extra information about user's groups
100 1 Jean-Philippe Lang
101 7 Jean-Philippe Lang
+Examples+:
102 1 Jean-Philippe Lang
103 7 Jean-Philippe Lang
  GET /users/current.xml
104
105
Returns the details about the current user.
106
107 1 Jean-Philippe Lang
  GET /users/3.xml?include=memberships,groups
108
109
Returns the details about user ID 3, and additional detail about the user's project memberships.
110
111 18 Toshi MARUYAMA
+Response+:
112 1 Jean-Philippe Lang
113 18 Toshi MARUYAMA
<pre><code class="xml">
114 1 Jean-Philippe Lang
<user>
115
  <id>3</id>
116
  <login>jplang</login>
117
  <firstname>Jean-Philippe</firstname>
118
  <lastname>Lang</lastname>
119
  <mail>jp_lang@yahoo.fr</mail>
120
  <created_on>2007-09-28T00:16:04+02:00</created_on>
121 27 Mizuki ISHIKAWA
  <updated_on>2010-08-01T18:05:45+02:00</updated_on>
122 1 Jean-Philippe Lang
  <last_login_on>2011-08-01T18:05:45+02:00</last_login_on>
123 27 Mizuki ISHIKAWA
  <passwd_changed_on>2011-08-01T18:05:45+02:00</passwd_changed_on>
124 14 Go MAEDA
  <api_key>ebc3f6b781a6fb3f2b0a83ce0ebb80e0d585189d</api_key>
125 27 Mizuki ISHIKAWA
  <avatar_url></avatar_url>
126 14 Go MAEDA
  <status>1</status>
127 5 Rick Mason
  <custom_fields type="array" />
128 1 Jean-Philippe Lang
  <memberships type="array">
129 4 Jean-Philippe Lang
    <membership>
130
      <project name="Redmine" id="1"/>
131
      <roles type="array">
132
        <role name="Administrator" id="3"/>
133
        <role name="Contributor" id="4"/>
134 1 Jean-Philippe Lang
      </roles>
135
    </membership>
136
  </memberships>
137
  <groups type="array">
138
    <group id="20" name="Developers"/>
139
  </groups>
140
</user>
141
</code></pre>
142 4 Jean-Philippe Lang
143 21 Cyril Jouve
If the user doing the request is not admin, it depends on the requested user:
144
145 22 Cyril Jouve
  * if the user is not locked and is not admin, the endpoint returns a user object with the fields @firstname@, @lastname@, @mail@, @created_on@
146
  * if the user is not locked and is admin, the endpoint returns a user object with the fields @firstname@, @lastname@, @created_on@, @last_login_on@
147 21 Cyril Jouve
  * if the user is locked, the endpoint returns 404 status code
148 22 Cyril Jouve
  * if the user is the requesting user, you will also have the fields @login@, @api_key@
149 21 Cyril Jouve
150
If the user doing the request is admin, a user object is always returned (blocked or not). It will have some more details:
151 9 Jean-Baptiste Barth
* @api_key@ : the API key of the user, visible for admins and for yourself (added in 2.3.0)
152
* @status@ : a numeric id representing the status of the user, visible for admins only (added in 2.4.0). See "app/models/principal.rb":/projects/redmine/repository/entry/trunk/app/models/principal.rb#L22-25 for a list of available statuses.
153
154 7 Jean-Philippe Lang
h3. PUT
155 4 Jean-Philippe Lang
156 7 Jean-Philippe Lang
Updates a user.
157 4 Jean-Philippe Lang
158 20 Cyril Jouve
This endpoint requires admin privileges.
159
160 1 Jean-Philippe Lang
+Example+:
161
162 7 Jean-Philippe Lang
  PUT /users/20.xml
163 1 Jean-Philippe Lang
164
+Parameters+:
165
166
* @user@ (required): a hash of the user attributes (same as for user creation)
167 24 Kenan Dervisevic
* @admin@ (optional): possible values are _true_ or _false_, gives user admin rights in the instance
168 30 Lorenzo Meneghetti
* @custom_fields@ - See [[Rest_api#Working-with-custom-fields|Custom fields]]
169 1 Jean-Philippe Lang
170 7 Jean-Philippe Lang
h3. DELETE
171 20 Cyril Jouve
172
This endpoint requires admin privileges.
173 1 Jean-Philippe Lang
174 7 Jean-Philippe Lang
Deletes a user.
175 4 Jean-Philippe Lang
176 7 Jean-Philippe Lang
+Example+:
177 1 Jean-Philippe Lang
178 7 Jean-Philippe Lang
  DELETE /users/20.xml
179 1 Jean-Philippe Lang
180
+Response+:
181 4 Jean-Philippe Lang
182 26 Go MAEDA
  * @204 No Content@: user was deleted
183 7 Jean-Philippe Lang
184
h2. See also
185
186
* The [[Rest_Memberships|Memberships API]] for adding or removing a user from a project.
187
* The [[Rest_Groups|Groups API]] for adding or removing a user from a group.