|
1
|
# JSON API: /user |
|
2
|
([⬑JSON API Index](index.md)) |
|
3
|
|
|
4
|
Jump to: |
|
5
|
|
|
6
|
* [Get User Info](#get) |
|
7
|
* [List Users](#list) |
|
8
|
* [Save User](#save) |
|
9
|
|
|
10
|
--- |
|
11
|
|
|
12
|
<a id="get"></a> |
|
13
|
# Get User Info |
|
14
|
|
|
15
|
**Status:** implemented 20110927. |
|
16
|
|
|
17
|
**Required privileges:** "a" or "s" |
|
18
|
|
|
19
|
**Request:** |
|
20
|
|
|
21
|
- POST `/json/user/get`\ |
|
22
|
with `POST.payload.name=USERNAME` |
|
23
|
- `/json/user/get?name=USERNAME` |
|
24
|
|
|
25
|
**Response payload example:** |
|
26
|
|
|
27
|
```json |
|
28
|
{ |
|
29
|
"uid":1, |
|
30
|
"name":"stephan", |
|
31
|
"capabilities":"abcdefhgijkmnopqrstuvwxz", |
|
32
|
"info":"https://wanderinghorse.net/home/stephan/", |
|
33
|
"timestamp":1316122562 |
|
34
|
} |
|
35
|
``` |
|
36
|
|
|
37
|
(What does that timestamp field represent, anyway?) |
|
38
|
|
|
39
|
<a id="list"></a> |
|
40
|
# List Users |
|
41
|
|
|
42
|
**Status:** implemented 20110927. |
|
43
|
|
|
44
|
**Required privileges:** "a" or "s" |
|
45
|
|
|
46
|
**Request:** `/json/user/list` |
|
47
|
|
|
48
|
**Response payload example:** |
|
49
|
|
|
50
|
```json |
|
51
|
[ |
|
52
|
{ |
|
53
|
"uid":1, |
|
54
|
"name":"stephan", |
|
55
|
"capabilities":"abcdefhgijkmnoprstuvwxz", |
|
56
|
"info":"", |
|
57
|
"timestamp":1316122562 |
|
58
|
}, |
|
59
|
... more users... |
|
60
|
] |
|
61
|
``` |
|
62
|
|
|
63
|
|
|
64
|
<a id="save"></a> |
|
65
|
# Save User |
|
66
|
|
|
67
|
Only admin/setup users may modify accounts other than their own. |
|
68
|
|
|
69
|
**Status:** implemented 20111021 *but* it is missing "login group" |
|
70
|
support, so changes do not yet propagate to other repos within a group. |
|
71
|
|
|
72
|
**Required privileges:** 'p' or 'a' or 's', depending on the context. |
|
73
|
|
|
74
|
**Request:** `/json/user/save` |
|
75
|
|
|
76
|
All request options must come from the `POST.payload` and/or GET/CLI |
|
77
|
parameters (exception: "name" must come from POST.payload or CLI). |
|
78
|
GET/CLI parameters take precedence over those in `POST.payload`, the |
|
79
|
intention being to use an input file as a template and overriding the |
|
80
|
template's defaults via the CLI. The options include: |
|
81
|
|
|
82
|
- `name=string` Specifies the user name to change. When changing a |
|
83
|
user's name, the current uid and the new name must be specified.\ |
|
84
|
**Achtung:** due to fossil-internal ambiguity in the handling of the |
|
85
|
"name" parameter, this parameter must come from the `POST.payload` |
|
86
|
data or it will not be recognized. In CLI mode it may be specified |
|
87
|
with the `--name` flag. |
|
88
|
- `uid=int` Specifies the uid to change. At least one of uid or name are |
|
89
|
required. A uid of -1 means to create a new user, in which case the |
|
90
|
name must be provided. |
|
91
|
- `password=string` Optionally changes the user's password. When |
|
92
|
renaming existing or creating new users, be sure to always provide a |
|
93
|
new password because any old password hash is invalidated by the |
|
94
|
name change. |
|
95
|
- `info=string` Optionally changes the user's info field. |
|
96
|
- `capabilities=string` Optionally changes the user's capabilities |
|
97
|
field. |
|
98
|
- `forceLogout=bool` (=false, or true when renaming) Optionally clears |
|
99
|
any current login info for the current user, which will invalidate |
|
100
|
any active session. Requires 'a' or 's' privileges. Intended to be |
|
101
|
used when disabling a user account, to ensure that any open session |
|
102
|
is invalidated. When a user is renamed this option is implied (and |
|
103
|
cannot be disabled) because renaming invalidates any currently |
|
104
|
stored auth token (because the old name is part of the hash |
|
105
|
equation). |
|
106
|
|
|
107
|
Fields which are not provided in the request will not be modified. |
|
108
|
Non-admin/setup users cannot edit other users and may only change their |
|
109
|
own data if they have the 'p' (password) privilege. |
|
110
|
|
|
111
|
As of 20120217, users who do not have the setup privilege may neither |
|
112
|
change the setup privilege for any user nor edit another user who has |
|
113
|
that privilege. That is, only users with setup access may propagate or |
|
114
|
remove setup status and accounts with the setup privilege may only be |
|
115
|
edited by themselves and other setup users. |
|
116
|
|
|
117
|
**Response payload:** Same as user/get, using the new/saved state of the |
|
118
|
modified user. |
|
119
|
|
|
120
|
Example usage from the command line: |
|
121
|
|
|
122
|
```console |
|
123
|
$ fossil json user save --name drh --password sqlite3 \ |
|
124
|
--capabilities "as" --info "DRH" |
|
125
|
$ fossil json user save --uid 1 --name richard \ |
|
126
|
--password fossil \ |
|
127
|
--info "Previously known as drh" |
|
128
|
``` |
|
129
|
|
|
130
|
**Warnings:** |
|
131
|
|
|
132
|
- When creating a new user or renaming a user, if no (new) password is |
|
133
|
specified in the save request then the user will not be able to log |
|
134
|
in because the previous password (for existing users) is hashed |
|
135
|
against the old name. |
|
136
|
- Renaming a user invalidates any active login token because his old |
|
137
|
name is a part of the hash. i.e. the user must log back in with the |
|
138
|
new name after being renamed. |
|
139
|
|
|
140
|
**TODOs:** |
|
141
|
|
|
142
|
- Login group support. |
|
143
|
|