10346: Document api_clients and trusted client.
[arvados.git] / doc / api / tokens.html.textile.liquid
index 458c41b574ed29027bc31b32fe2c6b6594cb25c3..83b0858f46f879400bacccd77f0a10b6877b9f85 100644 (file)
@@ -14,8 +14,20 @@ Browser based applications can perform log in via the following flow:
 # The "login" link takes the browser to the login page (this may involve several redirects)
 # The user logs in.  API server authenticates the user and issues a new API token.
 # The browser is redirected to the login page URL provided in @return_to=XXX@ with the addition of @?api_token=xxxxapitokenxxxx@.
-# The web application gets the login request with the included API token.
+# The web application gets the login request with the included authorization token.
 
 h2. Creating tokens via the API
 
 Use the @create@ method of the "API client authorizations":{{site.baseurl}}/api/methods/api_client_authorizations.html resource.
+
+h2. Trusted API clients
+
+The "api_clients" resource applies access restrictions to web applications that have gone through the browser login flow.
+
+After the user has authenticated, but before an authorization token is issued and browser redirect sent (sending the browser back to the @return_to@ login page bearing @api_token@), the server strips the path and query portion from @return_to@ to get @url_prefix@ finds or creates an ApiClient object.  The newly issued API client authorization (API token) is associated with this ApiClient object.
+
+API clients may be marked as "trusted".  An authorization token associated with a "trusted" client is permitted to list authorization tokens on "API client authorizations":{{site.baseurl}}/api/methods/api_client_authorizations.html .
+
+A authorization token which is not associated with a trusted client may only use the @current@ method to query its own api_client_authorization object.  The "untrusted" token is forbidden performing any other operations on API client authorizations, such as listing other authorizations or creating new authorizations.
+
+Authorization tokens which are not issued via the browser login flow (created directly via the API) will not have an associated api client.  This means authorization tokens created via the API are always "untrusted".