doc/api/methods/users.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "users"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/users@
  14
  15 Object type: @tpzed@
  16
  17 Example UUID: @zzzzz-tpzed-0123456789abcde@
  18
  19 h2. Resource
  20
  21 Users represent individuals with access to the Arvados cluster.
  22
  23 Each User has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  24
  25 table(table table-bordered table-condensed).
  26 |_. Attribute|_. Type|_. Description|_. Example|
  27 |email|string|||
  28 |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.||
  29 |first_name|string|||
  30 |last_name|string|||
  31 |identity_url|string|||
  32 |is_admin|boolean|||
  33 |prefs|hash|||
  34 |default_owner_uuid|string|||
  35 |is_active|boolean|||
  36 |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.||
  37
  38 h2. Methods
  39
  40 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  41
  42 Required arguments are displayed in %{background:#ccffcc}green%.
  43
  44 h3. create
  45
  46 Create a new User.
  47
  48 Arguments:
  49
  50 table(table table-bordered table-condensed).
  51 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  52 |user|object||query||
  53
  54 h3. current
  55
  56 Get the user associated with the provided API token.
  57
  58 Arguments:
  59
  60 table(table table-bordered table-condensed).
  61 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  62
  63 h3. delete
  64
  65 Delete an existing User.
  66
  67 Arguments:
  68
  69 table(table table-bordered table-condensed).
  70 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  71 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
  72
  73 Arguments:
  74
  75 table(table table-bordered table-condensed).
  76 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  77 {background:#ccffcc}.|uuid|string||path||
  78
  79 h3. get
  80
  81 Gets a User's metadata by UUID.
  82
  83 Arguments:
  84
  85 table(table table-bordered table-condensed).
  86 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  87 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
  88
  89 h3. list
  90
  91 List users.
  92
  93 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  94
  95 h3. system
  96
  97 Get the user record for the "system user.":{{site.baseurl}}/api/permission-model.html#system
  98
  99 Arguments:
 100
 101 table(table table-bordered table-condensed).
 102 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 103
 104 h3. update
 105
 106 Update attributes of an existing User.
 107
 108 Arguments:
 109
 110 table(table table-bordered table-condensed).
 111 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 112 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
 113 |user|object|The new attributes.|query||
 114
 115 h3(#update_uuid). update_uuid
 116
 117 Change the UUID of an existing user, updating all database references accordingly.
 118
 119 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.
 120
 121 Arguments:
 122
 123 table(table table-bordered table-condensed).
 124 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 125 {background:#ccffcc}.|uuid|string|The current UUID of the user in question.|path|@zzzzz-tpzed-12345abcde12345@|
 126 {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@|
 127
 128 h3. setup
 129
 130 Set up a user.  Adds the user to the "All users" group.  Enables the user to invoke @activate@.  See "user management":{{site.baseurl}}/admin/user-management.html for details.
 131
 132 Arguments:
 133
 134 table(table table-bordered table-condensed).
 135 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 136 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|query||
 137
 138 h3. activate
 139
 140 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/user-management.html#user_agreements for details.
 141
 142 Arguments:
 143
 144 table(table table-bordered table-condensed).
 145 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 146 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|query||
 147
 148 h3. unsetup
 149
 150 Remove the user from the "All users" group and deactivate the user.  See "user management":{{site.baseurl}}/admin/user-management.html for details.
 151
 152 Arguments:
 153
 154 table(table table-bordered table-condensed).
 155 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 156 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
 157
 158 h3. merge
 159
 160 Transfer ownership of data from the "old" user account to the "new" user account.  When @redirect_to_new_user@ is @true@ this also causes logins to the "old" account to be redirected to the "new" account.  The "old" user account that was redirected becomes invisible in user listings.
 161
 162 See "Merge user accounts":{{site.baseurl}}/admin/link-accounts.html , "Reassign user data ownership":{{site.baseurl}}/admin/reassign-ownership.html and "Linking alternate login accounts":{{site.baseurl}}/user/topics/link-accounts.html for examples of how this method is used.
 163
 164 Must supply either @new_user_token@ (the currently authorized user will be the "old" user), or both @new_user_uuid@ and @old_user_uuid@ (the currently authorized user must be an admin).
 165
 166 Arguments:
 167
 168 table(table table-bordered table-condensed).
 169 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 170 |new_user_token|string|A valid token for the "new" user|query||
 171 |new_user_uuid|uuid|The uuid of the "new" account|query||
 172 |old_user_uuid|uuid|The uuid of the "old" account|query||
 173 |new_owner_uuid|uuid|The uuid of a project to which objects owned by the "old" user will be reassigned.|query||
 174 |redirect_to_new_user|boolean|If true, also redirect login and reassign authorization credentials from "old" user to the "new" user|query||
 175
 176 h3. authenticate
 177
 178 Create a new API token based on username/password credentials.  Returns an "API client authorization":api_client_authorizations.html object containing the API token, or an "error object.":../requests.html#errors
 179
 180 Valid credentials are determined by the choice of "configured login backend.":{{site.baseurl}}/install/setup-login.html
 181
 182 Note: this endpoint cannot be used with login backends that use web-based third party authentication, such as Google or OpenID Connect.
 183
 184 Arguments:
 185
 186 table(table table-bordered table-condensed).
 187 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 188 {background:#ccffcc}.|username|string|The username.|body||
 189 {background:#ccffcc}.|password|string|The password.|body||