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||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@|