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 |is_active|boolean|||
  35 |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.||
  36
  37 h2. Methods
  38
  39 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  40
  41 Required arguments are displayed in %{background:#ccffcc}green%.
  42
  43 h3. create
  44
  45 Create a new User.
  46
  47 Arguments:
  48
  49 table(table table-bordered table-condensed).
  50 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  51 |user|object||query||
  52
  53 h3(#current). current
  54
  55 Get the user associated with the provided API token.
  56
  57 Arguments:
  58
  59 table(table table-bordered table-condensed).
  60 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  61
  62 h3. delete
  63
  64 Delete an existing User.
  65
  66 Arguments:
  67
  68 table(table table-bordered table-condensed).
  69 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  70 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
  71
  72 Arguments:
  73
  74 table(table table-bordered table-condensed).
  75 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  76 {background:#ccffcc}.|uuid|string||path||
  77
  78 h3. get
  79
  80 Gets a User's metadata by UUID.
  81
  82 Arguments:
  83
  84 table(table table-bordered table-condensed).
  85 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  86 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
  87
  88 h3. list
  89
  90 List users.
  91
  92 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  93
  94 h3. system
  95
  96 Get the user record for the "system user.":{{site.baseurl}}/api/permission-model.html#system
  97
  98 Arguments:
  99
 100 table(table table-bordered table-condensed).
 101 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 102
 103 h3. update
 104
 105 Update attributes of an existing User.
 106
 107 Arguments:
 108
 109 table(table table-bordered table-condensed).
 110 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 111 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
 112 |user|object|The new attributes.|query||
 113
 114 h3. setup
 115
 116 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.
 117
 118 Arguments:
 119
 120 table(table table-bordered table-condensed).
 121 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 122 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|query||
 123
 124 h3. activate
 125
 126 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.
 127
 128 Arguments:
 129
 130 table(table table-bordered table-condensed).
 131 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 132 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|query||
 133
 134 h3. unsetup
 135
 136 Remove the user from the "All users" group and deactivate the user.  See "user management":{{site.baseurl}}/admin/user-management.html for details.
 137
 138 Arguments:
 139
 140 table(table table-bordered table-condensed).
 141 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 142 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
 143
 144 h3. merge
 145
 146 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.
 147
 148 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.
 149
 150 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).
 151
 152 Arguments:
 153
 154 table(table table-bordered table-condensed).
 155 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 156 |new_user_token|string|A valid token for the "new" user|query||
 157 |new_user_uuid|uuid|The uuid of the "new" account|query||
 158 |old_user_uuid|uuid|The uuid of the "old" account|query||
 159 |new_owner_uuid|uuid|The uuid of a project to which objects owned by the "old" user will be reassigned.|query||
 160 |redirect_to_new_user|boolean|If true, also redirect login and reassign authorization credentials from "old" user to the "new" user|query||
 161
 162 h3. authenticate
 163
 164 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
 165
 166 Valid credentials are determined by the choice of "configured login backend.":{{site.baseurl}}/install/setup-login.html
 167
 168 Note: this endpoint cannot be used with login backends that use web-based third party authentication, such as Google or OpenID Connect.
 169
 170 Arguments:
 171
 172 table(table table-bordered table-condensed).
 173 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 174 {background:#ccffcc}.|username|string|The username.|body||
 175 {background:#ccffcc}.|password|string|The password.|body||