Specification overview

The following documentation lists only the status codes returned by the method itself, if you get a response code not listed here, try the General response codes page.

Basic user management

Basic user management takes care of the very basic functionalities related to user management. It allows you to get a list of users, add a user to the system, set/verify the password and delete a user. The basic user management facilities provided by RestAuth are as simple as in any way possible. For all important operations you only have to check the status code returned to get the answer to your question - there is no need to parse the response body at all. The only exception to this is getting a list of all known users.

what	method	URI	parameters	notable status codes
Create a user	POST	/users/	user The username of the user to create password Optional. The password for this user. If not set or set to an empty value, the user has no password. properties Optional. Initial properties for the new user. groups Optional. Initial groups for the new user.	201 Created If the creation of the user succeeded 409 Conflict If the user already exists 412 Precondition Failed If the submitted username or password is not acceptable to the system. See also: Restriction on entity names.
Get a list of users	GET	/users/		200 Ok Always returned
Verify that a user exists	GET	/users/<user>/		200 Ok If the user exists 404 Not Found If the user does not exist
Verify password	POST	/users/<user>/	password The password to check groups Optional. A list of groups that the user has to be a member of	204 No Content If the given password is the right one for the given user 404 Not Found If the user is not found or if the password does not match.
Change password	PUT	/users/<user>/	password Optional. The new password for this user. If not set or set to an empty value, the user has no password.	204 No Content If the password was successfully updated 404 Not Found If the username does not exist 412 Precondition Failed If the new username or password is not acceptable to the system. See also: Restriction on entity names.
Delete a user	DELETE	/users/<user>/		204 No Content If the user really was deleted 404 Not Found If the user was not found

Managing user properties

It is possible to use RestAuth to store user properties like email-addresses, real names, etc. The keys that applications use for certain properties is by convention only, so applications have to take care to map their internal names for a property to the name RestAuth knows about.

what	method	request	parameters	status codes
Get all properties	GET	/users/<user>/props/		200 OK I the request went ok 404 Not Found If the user was not found
Create a new property	POST	/users/<user>/props/	prop The name of the property to set value The value of the property	200 OK If the property was successfully set 404 Not Found If the user does not exist. 409 Conflict If the resource already existed
Set values of multiple properties	PUT	/users/<user>/props/	A dictionary of key/value pairs of properties to set.	200 OK If the properties were set. 404 Not Found If the user doesn't exist.
Get value of a property	GET	/users/<user>/props/<prop>/		200 OK If the user and the specified property exists 404 Not Found If either the user or the property does not exist.
Set value of a property	PUT	/users/<user>/props/<prop>/	value The (new) value of the addressed property	200 OK If the property was set, regardless if it previously existed or not. 404 Not Found If the user was not found
Delete a property	DELETE	/users/<user>/props/<prop>/		200 OK If the resource was deleted 404 Not Found If the resource was not found

Group management

Many systems use a group based model to manage privileges granted to individual users. You can use RestAuth to manage the groups that a user is in. Services always only have access to their own set of groups, so e.g. becoming administrator in one service does not make you administrator in any other service. It is however possible to inherit group membership from other groups, that are not necessarily associated with any service. So you could define an 'admin' group and define that the admin group of every service inherits its members from that general group. It is not possible for a service to manage groups outside of its own scope, including groups not associated with any service.

what	method	request	parameters	status codes
Get a list of groups	GET	/groups/	user (optional) If given, only return groups that the user is a member of	200 OK If no error occured
Create a group	POST	/groups/	group name of the group to create	201 Created If the group was successfully created 409 Conflict If the group already exists
Set groups of a user	PUT	/groups/	user Name of the user to set the groups for groups List of new groups for the user	204 No content If the operation was successful 404 Not Found I f the user does not exist
Verify that a group exists	GET	/groups/<group>/		204 No Content If the group exists 404 Not Found If the group does not exist
Delete a group	DELETE	/groups/<group>/		204 No Content If the group was removed. 404 Not Found If the group was not found.
Get all users in a group	GET	/groups/<group>/users/		200 Ok If the group exists 404 Not Found If the group does not exist
Add a user to a group	POST	/groups/<group>/users/	user The user to add to the named group	204 No Content If the user was successfully added to the group 404 Not Found If the user was not found or if the group is not found.
Set users of a group	PUT	/groups/<group>/users/	users The new users of a group	204 No Content If the list of users users was successfully set 404 Not Found If the group was not found or any of the given users is not found.
Verify that a user is in a group	GET	/groups/<group>/users/<user>/		204 No Content If the user is in the group. 404 Not Found If either group or user does not exist or if the user is not in the group. In the latter case, the response will not contain a body.
Remove a user from a group	DELETE	/groups/<group>/users/<user>/		204 No Content If the user was removed from the group or the user was not in the group 404 Not Found If the group or the user do not exist
Get a list of sub-groups	GET	/groups/<group>/groups/		200 Ok If no error occured. 404 Not Found If the group does not exist.
Add a group to a group	POST	/groups/<group>/groups/	group The name of the child group to be added to this group	204 No Content If no error occured. 404 Not Found If the child group was not found or if the parent group is not found.
Set subgroups of a group	PUT	/groups/<group>/groups/	groups The new groups of a group	204 No Content If the list of groups users was successfully set 404 Not Found If the group was not found or any of the given subgroups is not found.
Verify that a group is in a group	GET	/groups/<group>/groups/<subgroup>/		204 No Content If the group is in the group. 404 Not Found If either group or group does not exist or if the subgroup is not in the group. In the latter case, the response will not contain a body.
Remove a group from a group	DELETE	/groups/<group>/groups/<subgroup>/		204 No Content If the user really was deleted 404 Not Found If the group was not found

Dry-Runs

See Doing dry-runs.