X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/b54d7820e899733ce10b8960b1f04d0481f2e11f..14a6eb786a0d01e86ccae7645e880661caf6f0cb:/doc/api/methods/users.html.textile.liquid diff --git a/doc/api/methods/users.html.textile.liquid b/doc/api/methods/users.html.textile.liquid index 9fbbda54e6..4c33f2afe8 100644 --- a/doc/api/methods/users.html.textile.liquid +++ b/doc/api/methods/users.html.textile.liquid @@ -3,15 +3,45 @@ layout: default navsection: api navmenu: API Methods title: "users" - ... +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. -h1. users +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} -Required arguments are displayed in %{background:#ccffcc}green%. +API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/users@ + +Object type: @tpzed@ + +Example UUID: @zzzzz-tpzed-0123456789abcde@ + +h2. Resource + +Users represent individuals with access to the Arvados cluster. + +Each User has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html: +table(table table-bordered table-condensed). +|_. Attribute|_. Type|_. Description|_. Example| +|email|string||| +|username|string|The username used for the user's git repositories and virtual machine logins. Usernames must start with a letter, and contain only alphanumerics. When a new user is created, a default username is set from their e-mail address. Only administrators may change the username.|| +|first_name|string||| +|last_name|string||| +|identity_url|string||| +|is_admin|boolean||| +|prefs|hash||| +|default_owner_uuid|string||| +|is_active|boolean||| +|writable_by|array|List of UUID strings identifying Groups and other Users that can modify this User object. This will include the user's owner_uuid and, for administrators and users requesting their own User object, the requesting user's UUID.|| + +h2. Methods + +See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@. + +Required arguments are displayed in %{background:#ccffcc}green%. -h2. create +h3. create Create a new User. @@ -21,16 +51,16 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | |user|object||query|| -h2. current +h3. current -current users +Get the user associated with the provided API token. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -h2. delete +h3. delete Delete an existing User. @@ -40,87 +70,87 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path|| -h2. destroy - -destroy users - Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string||path|| -h2. event_stream +h3. get -event_stream users +Gets a User's metadata by UUID. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| +{background:#ccffcc}.|uuid|string|The UUID of the User in question.|path|| -h2. get +h3. list -Gets a User's metadata by UUID. +List users. + +See "common resource list method.":{{site.baseurl}}/api/methods.html#index + +h3. system + +Get the user record for the "system user.":{{site.baseurl}}/api/permission-model.html#system Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string|The UUID of the User in question.|path|| -h2. index +h3. update -index users +Update attributes of an existing User. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -|order|string||query|| -|where|object||query|| +{background:#ccffcc}.|uuid|string|The UUID of the User in question.|path|| +|user|object|The new attributes.|query|| -h2. list +h3(#update_uuid). update_uuid -List users. +Change the UUID of an existing user, updating all database references accordingly. + +This method can only be used by an admin user. It should only be used when the affected user is idle. New references to the affected user that are established _while the update_uuid operation is in progress_ might not be migrated as expected. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -|limit|integer (default 100)|Maximum number of users to return.|query|| -|order|string|Order in which to return matching users.|query|| -|pageToken|string|Page token.|query|| -|q|string|Query string for searching users.|query|| -|where|object|Conditions for filtering users.|query|| +{background:#ccffcc}.|uuid|string|The current UUID of the user in question.|path|@zzzzz-tpzed-12345abcde12345@| +{background:#ccffcc}.|new_uuid|string|The desired new UUID. It is an error to use a UUID belonging to an existing user.|query|@zzzzz-tpzed-abcde12345abcde@| -h2. show +h3. setup -show users +Set up a user. Adds the user to the "All users" group. Enables the user to invoke @activate@. See "user management":{{site.baseurl}}/admin/activation.html for details. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| +{background:#ccffcc}.|uuid|string|The UUID of the User in question.|query|| -h2. system +h3. activate -system users +Check that a user has is set up and has signed all the user agreements. If so, activate the user. Users can invoke this for themselves. See "user agreements":{{site.baseurl}}/admin/activation.html#user_agreements for details. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | +{background:#ccffcc}.|uuid|string|The UUID of the User in question.|query|| -h2. update +h3. unsetup -Update attributes of an existing User. +Remove the user from the "All users" group and deactivate the user. See "user management":{{site.baseurl}}/admin/activation.html for details. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path|| -|user|object||query||