doc/api/methods/api_client_authorizations.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "api_client_authorizations"
   6
   7 ...
   8
   9 See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
  10
  11 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/api_client_authorizations@
  12
  13 Required arguments are displayed in %{background:#ccffcc}green%.
  14
  15 h2. Resource
  16
  17 The @api_client_authorizations@ resource stores the API tokens that have been issued to permit access the API server.
  18
  19 An ApiClientAuthorization is *not* a generic Arvados resource.  The full list of properties that belong to an ApiClientAuthorization is:
  20
  21 table(table table-bordered table-condensed).
  22 |_. Attribute|_. Type|_. Description|_. Example|
  23 |uuid|string|An identifier used to refer to the token without exposing the actual token.||
  24 |api_token|string|The actual token string that is expected in the Authorization header.||
  25 |api_client_id|integer|-||
  26 |user_id|integer|-||
  27 |created_by_ip_address|string|-||
  28 |last_used_by_ip_address|string|The network address of the most recent client using this token.||
  29 |last_used_at|datetime|Timestamp of the most recent request using this token.||
  30 |expires_at|datetime|Time at which the token is no longer valid.  May be set to a time in the past in order to immediately expire a token.||
  31 |owner_uuid|string|The user associated with the token.  All operations using this token are checked against the permissions of this user.||
  32 |scopes|array|A list of resources this token is allowed to access.  A scope of ["all"] allows all resources.  See below.||
  33
  34 h3(#scope). Scopes
  35
  36 Scopes can restrict a token so it may only access certain resources.  This is in addition to normal permission checks for the user associated with the token.
  37
  38 Each entry in scopes consists of a @request_method@ and @request_path@, where the @request_method@ is a HTTP method (one of @GET@, @POST@, @PUT@ or @DELETE@) and @request_path@ is the request URI.  A given request is permitted if it matches a scopes exactly, or the scope ends with @/@ and the request string is a prefix of the scope.
  39
  40 As a special case, a scope of ["all"] allows all resources.
  41
  42 h4. Examples
  43
  44 A scope of @GET /arvados/v1/collections@ permits listing collections.
  45
  46 * Requests with different methods, such as creating a new collection using @POST /arvados/v1/collections@, will be rejected.
  47 * Requests to access other resources, such as @GET /arvados/v1/groups@, will be rejected.
  48 * Be aware that requests for specific records, such as @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will also be rejected.  This is because the scope @GET /arvados/v1/collections@ does not end in @/@
  49
  50 A scope of @GET /arvados/v1/collections/@ (with @/@ suffix) will permit access to individual collections.
  51
  52 * The request @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will succeed
  53 * Be aware that requests for listing @GET /arvados/v1/collections@ (no @/@ suffix) will be rejected, because it is not an exact match with @GET /arvados/v1/collections/@
  54
  55 To allow both listing objects and requesting individual objects, include both in the scope: @["GET /arvados/v1/collections", "GET /arvados/v1/collections/"]@
  56
  57 A narrow scope such as @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will disallow listing objects as well as disallow requesting any object other than those in the scope.
  58
  59 h2. Methods
  60
  61 h3(#create). create
  62
  63 Create a new ApiClientAuthorization.
  64
  65 Regular users may only create self-owned API tokens, but may provide a restricted "scope"#scope .  Administrators may create API tokens corresponding to any user.
  66
  67 Arguments:
  68
  69 table(table table-bordered table-condensed).
  70 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  71 |api_client_authorization|object||query||
  72
  73 h3. create_system_auth
  74
  75 create_system_auth api_client_authorizations
  76
  77 Arguments:
  78
  79 table(table table-bordered table-condensed).
  80 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  81 |api_client_id|integer||query||
  82 |scopes|array||query||
  83
  84 h3. delete
  85
  86 Delete an existing ApiClientAuthorization.
  87
  88 Arguments:
  89
  90 table(table table-bordered table-condensed).
  91 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  92 {background:#ccffcc}.|uuid|string|The UUID of the ApiClientAuthorization in question.|path||
  93
  94 h3. get
  95
  96 Gets a ApiClientAuthorization's metadata by UUID.
  97
  98 Arguments:
  99
 100 table(table table-bordered table-condensed).
 101 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 102 {background:#ccffcc}.|uuid|string|The UUID of the ApiClientAuthorization in question.|path||
 103
 104 h3. list
 105
 106 List api_client_authorizations.
 107
 108 Arguments:
 109
 110 table(table table-bordered table-condensed).
 111 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 112 |limit|integer (default 100)|Maximum number of api_client_authorizations to return.|query||
 113 |order|string|Order in which to return matching api_client_authorizations.|query||
 114 |filters|array|Conditions for filtering api_client_authorizations.|query||
 115
 116 h3. update
 117
 118 Update attributes of an existing ApiClientAuthorization.
 119
 120 Arguments:
 121
 122 table(table table-bordered table-condensed).
 123 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 124 {background:#ccffcc}.|uuid|string|The UUID of the ApiClientAuthorization in question.|path||
 125 |api_client_authorization|object||query||