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/activation.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/activation.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/activation.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||