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