split User into User Guide and API Reference

[arvados.git] / doc / api / authentication.textile

diff --git a/doc/api/authentication.textile b/doc/api/authentication.textile
new file mode 100644 (file)
index 0000000..fea46bb
--- /dev/null
+++ b/doc/api/authentication.textile
@@ -0,0 +1,39 @@
+---
+layout: default
+navsection: api
+title: Authentication
+navorder: 2
+---
+
+h1. Authentication
+
+Every API request (except the authentication API itself) includes an @access_token@ parameter.
+
+table(table table-bordered table-condensed).
+|Name|Type|Description|
+|access_token|string|Access token returned by OAuth 2.0 authorization procedure|
+
+Many resources contain "actor" attributes like @modified_by@.  An @access_token@ uniquely identifies a client (application or project) and an end-user.
+
+table(table table-bordered table-condensed).
+|Name|Type|Description|
+|modified_by_client|string|ID of API client|
+|modified_by_user|string|ID of authenticated user|
+
+h2. Authorizing a client application
+
+The Arvados API uses the "OAuth 2.0 protocol":http://tools.ietf.org/html/draft-ietf-oauth-v2-22 for authentication and authorization.
+
+h3. Register your client application
+
+Before an application can run on an Arvados cloud, it needs to be registered with the cloud. 
+
+That registration yields a @client_id@ and a @client_secret@. 
+
+h3. Obtain an access code
+
+A client obtains an access code by means of a standard Oauth 2.0 flow. The access code is granted to it by an authorized user. The client requests one or more scopes, which translate to a set of requested permissions (reading, writing, etc). Unless the access is to be short-lived, a refresh token is also granted to the application. 
+
+h3. Refresh the access code (optional)
+
+Access codes have a limited lifetime. A refresh token allows an application to request a new access token.
\ No newline at end of file