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). 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. setup
 116
 117 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.
 118
 119 Arguments:
 120
 121 table(table table-bordered table-condensed).
 122 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 123 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|query||
 124
 125 h3. activate
 126
 127 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.
 128
 129 Arguments:
 130
 131 table(table table-bordered table-condensed).
 132 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 133 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|query||
 134
 135 h3. unsetup
 136
 137 Remove the user from the "All users" group and deactivate the user.  See "user management":{{site.baseurl}}/admin/user-management.html for details.
 138
 139 Arguments:
 140
 141 table(table table-bordered table-condensed).
 142 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 143 {background:#ccffcc}.|uuid|string|The UUID of the User in question.|path||
 144
 145 h3. merge
 146
 147 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.
 148
 149 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.
 150
 151 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).
 152
 153 Arguments:
 154
 155 table(table table-bordered table-condensed).
 156 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 157 |new_user_token|string|A valid token for the "new" user|query||
 158 |new_user_uuid|uuid|The uuid of the "new" account|query||
 159 |old_user_uuid|uuid|The uuid of the "old" account|query||
 160 |new_owner_uuid|uuid|The uuid of a project to which objects owned by the "old" user will be reassigned.|query||
 161 |redirect_to_new_user|boolean|If true, also redirect login and reassign authorization credentials from "old" user to the "new" user|query||
 162
 163 h3. authenticate
 164
 165 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
 166
 167 Valid credentials are determined by the choice of "configured login backend.":{{site.baseurl}}/install/setup-login.html
 168
 169 Note: this endpoint cannot be used with login backends that use web-based third party authentication, such as Google or OpenID Connect.
 170
 171 Arguments:
 172
 173 table(table table-bordered table-condensed).
 174 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 175 {background:#ccffcc}.|username|string|The username.|body||
 176 {background:#ccffcc}.|password|string|The password.|body||