From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/json-api/api-user.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 www/json-api/api-user.md (limited to 'www/json-api/api-user.md') diff --git a/www/json-api/api-user.md b/www/json-api/api-user.md new file mode 100644 index 0000000..c4f055f --- /dev/null +++ b/www/json-api/api-user.md @@ -0,0 +1,142 @@ +# JSON API: /user +([⬑JSON API Index](index.md)) + +Jump to: + +* [Get User Info](#get) +* [List Users](#list) +* [Save User](#save) + +--- + + +# Get User Info + +**Status:** implemented 20110927. + +**Required privileges:** "a" or "s" + +**Request:** + +- POST `/json/user/get`\ + with `POST.payload.name=USERNAME` +- `/json/user/get?name=USERNAME` + +**Response payload example:** + +```json +{ + "uid":1, + "name":"stephan", + "capabilities":"abcdefhgijkmnopqrstuvwxz", + "info":"https://wanderinghorse.net/home/stephan/", + "timestamp":1316122562 +} +``` + +(What does that timestamp field represent, anyway?) + + +# List Users + +**Status:** implemented 20110927. + +**Required privileges:** "a" or "s" + +**Request:** `/json/user/list` + +**Response payload example:** + +```json +[ + { + "uid":1, + "name":"stephan", + "capabilities":"abcdefhgijkmnoprstuvwxz", + "info":"", + "timestamp":1316122562 + }, + ... more users... +] +``` + + + +# Save User + +Only admin/setup users may modify accounts other than their own. + +**Status:** implemented 20111021 *but* it is missing "login group" +support, so changes do not yet propagate to other repos within a group. + +**Required privileges:** 'p' or 'a' or 's', depending on the context. + +**Request:** `/json/user/save` + +All request options must come from the `POST.payload` and/or GET/CLI +parameters (exception: "name" must come from POST.payload or CLI). +GET/CLI parameters take precedence over those in `POST.payload`, the +intention being to use an input file as a template and overriding the +template's defaults via the CLI. The options include: + +- `name=string` Specifies the user name to change. When changing a + user's name, the current uid and the new name must be specified.\ + **Achtung:** due to fossil-internal ambiguity in the handling of the + "name" parameter, this parameter must come from the `POST.payload` + data or it will not be recognized. In CLI mode it may be specified + with the `--name` flag. +- `uid=int` Specifies the uid to change. At least one of uid or name are + required. A uid of -1 means to create a new user, in which case the + name must be provided. +- `password=string` Optionally changes the user's password. When + renaming existing or creating new users, be sure to always provide a + new password because any old password hash is invalidated by the + name change. +- `info=string` Optionally changes the user's info field. +- `capabilities=string` Optionally changes the user's capabilities + field. +- `forceLogout=bool` (=false, or true when renaming) Optionally clears + any current login info for the current user, which will invalidate + any active session. Requires 'a' or 's' privileges. Intended to be + used when disabling a user account, to ensure that any open session + is invalidated. When a user is renamed this option is implied (and + cannot be disabled) because renaming invalidates any currently + stored auth token (because the old name is part of the hash + equation). + +Fields which are not provided in the request will not be modified. +Non-admin/setup users cannot edit other users and may only change their +own data if they have the 'p' (password) privilege. + +As of 20120217, users who do not have the setup privilege may neither +change the setup privilege for any user nor edit another user who has +that privilege. That is, only users with setup access may propagate or +remove setup status and accounts with the setup privilege may only be +edited by themselves and other setup users. + +**Response payload:** Same as user/get, using the new/saved state of the +modified user. + +Example usage from the command line: + +```console +$ fossil json user save --name drh --password sqlite3 \ + --capabilities "as" --info "DRH" +$ fossil json user save --uid 1 --name richard \ + --password fossil \ + --info "Previously known as drh" +``` + +**Warnings:** + +- When creating a new user or renaming a user, if no (new) password is + specified in the save request then the user will not be able to log + in because the previous password (for existing users) is hashed + against the old name. +- Renaming a user invalidates any active login token because his old + name is a part of the hash. i.e. the user must log back in with the + new name after being renamed. + +**TODOs:** + +- Login group support. -- cgit v1.3.1