usergrid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timangl...@apache.org
Subject svn commit: r1543106 [4/23] - in /incubator/usergrid/site: ./ content/ content/bootstrap/ content/community/ content/css/ content/docs/ content/font/ content/img/ content/img/check_flat/ content/js/ content/static/ layouts/ lib/ lib/helpers/ publish/ p...
Date Mon, 18 Nov 2013 18:51:22 GMT
Added: incubator/usergrid/site/content/docs/admin-user.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/admin-user.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/admin-user.md (added)
+++ incubator/usergrid/site/content/docs/admin-user.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,781 @@
+---
+title: Admin user
+category: docs
+layout: docs
+---
+
+Admin user
+==========
+
+[See all management
+resources](/docs/usergrid/content/management-resources)[![](/docs/sites/docs/files/learnmore%20arrow_0.png)](/docs/usergrid/content/management-resources)
+
+An admin user has full access to perform any operation on all
+organization accounts of which the admin user is a member. Using the App
+services API, you can create, update, or retrieve an admin user. You can
+also set or reset an admin user's password, activite or reactivate an
+admin user, and get an admin user's activity feed.
+
+In addition, you can add,  retrieve, or remove an admin user from an
+organization. For information on these organization-related operations,
+see [Organization](/organization).
+
+**Note:** Although not shown in the API examples below, you need to
+provide a valid access token with each API call. See [Authenticating
+users and application
+clients](/authenticating-users-and-application-clients) for details.
+
+Creating an admin user
+----------------------
+
+Use the POST method to create an admin user.
+
+### Request URI
+
+POST /management/organizations/{org}/users {request body}
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter                            | Description                          |
++======================================+======================================+
+| request body                         | One or more sets of user properties, |
+|                                      | of which username is mandatory and   |
+|                                      | must be unique:                      |
+|                                      |                                      |
+|                                      |     {                                |
+|                                      |       "username" : "jim.admin",      |
+|                                      |       "email" : "jim.admin@gmail.com |
+|                                      | ",                                   |
+|                                      |       "name" : "Jim Admin",          |
+|                                      |       "password" : "test12345"       |
+|                                      |     }                                |
++--------------------------------------+--------------------------------------+
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_create_admin_user)
+-   [JavaScript (HTML5)](#javascript_create_admin_user)
+-   [Ruby](#ruby_create_admin_user)
+-   [Node.js](#nodejs_create_admin_user)
+
+<!-- -->
+
+    curl -X -i POST "https://api.usergrid.com/management/organizations/my-org/users" -d '{"username":"jim.admin","name":"Jim Admin","email":"jim.admin@gmail.com","password":"test12345"}'
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    result = mgmt.create_user username: 'jim.admin', name: 'Jim Admin', email: 'jim.admin@gmail.com', password: 'test12345'
+    jim_admin = result.entity
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'POST',
+        endpoint:'management/organizations/my-org/users',
+        body:{ username:'jim.admin', name:'Jim Admin', email:'jim.admin@gmail.com',  
+        password:'test12345' }
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — POST failed
+        } else {
+            //success — data will contain raw results from API call        
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "post",
+      "status": "ok",
+      "data":  {
+        "user":  {
+          "applicationId": "00000000-0000-0000-0000-000000000001",
+          "username": "jim.admin",
+          "name": "Jim Admin",
+          "email": "jim.admin@gmail.com",
+          "activated": true,
+          "disabled": false,
+          "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591",
+          "adminUser": true,
+          "displayEmailAddress": "jim.admin <jim.admin@gmail.com>",
+          "htmldisplayEmailAddress": "jim.admin <a href="mailto:jim.admin@gmail.com">jinm.admin@gmail.com</a>"
+        }
+      },
+      "timestamp": 1349390189106,
+      "duration": 11808
+    }
+
+Updating an admin user
+----------------------
+
+Use the PUT method to update an admin user.
+
+### Request URI
+
+PUT /management/organizations/{org}/users/{user|username|email|uuid}
+{request body}
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter                            | Description                          |
++======================================+======================================+
+| string user|string username|string   | Admin username, name, email address, |
+| email|arg uuid                       | or UUID.                             |
++--------------------------------------+--------------------------------------+
+| request body                         | One or more sets of user properties: |
+|                                      |                                      |
+|                                      |     {                                |
+|                                      |       "city" : "San Francisco",      |
+|                                      |       "state" : "California"         |
+|                                      |     }                                |
++--------------------------------------+--------------------------------------+
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_update_admin_user)
+-   [JavaScript (HTML5)](#javascript_update_admin_user)
+-   [Ruby](#ruby_update_admin_user)
+-   [Node.js](#nodejs_update_admin_user)
+
+<!-- -->
+
+    curl -X -i PUT "https://api.usergrid.com/management/organizations/my-org/users/jim.admin" -d '{"city":"San Francisco","state":"California"}'
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    jim_admin = mgmt['users/jim.admin'].entity
+    jim_admin.city = 'San Francisco'
+    jim_admin.state = 'California'
+    jim_admin.save
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'PUT',
+        endpoint:'management/organizations/my-org/users/jim.admin',
+        body:{ email:'john.doe@mail.com', city:'San Francisco', state:'California' }
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — PUT failed
+        } else {
+            //success — data will contain raw results from API call        
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "update user info",
+      "timestamp": 1349479321874,
+      "duration": 0
+    }
+
+Getting an admin user
+---------------------
+
+Use the GET method to retrieve details about an admin user.
+
+### Request URI
+
+GET /management/organizations/{org}/users/{user|username|email|uuid}
+
+### Parameters
+
+  Parameter                                           Description
+  --------------------------------------------------- -----------------------------------------------
+  string user|string username|string email|arg uuid   Admin username, name, email address, or UUID.
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_get_admin_user)
+-   [JavaScript (HTML5)](#javascript_get_admin_user)
+-   [Ruby](#ruby_get_admin_user)
+-   [Node.js](#nodejs_get_admin_user)
+
+<!-- -->
+
+    curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    jim_admin = mgmt['users/jim.admin'].entity
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'GET',
+        endpoint:'management/organizations/my-org/users/jim.admin'
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — GET failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "get admin user",
+      "status": "ok",
+      "data":  {
+        "username": "jim.admin",
+        "token": "YWMt4NqE8Q9GEeLYJhIxPSiO4AAAATo5fQfcG0cEd2h9nwmDmRorkNNrEeQyDOF",
+        "email": "edort1@gmail.com",
+        "organizations":  {
+          "jim.admin":  {
+            "users":  {
+              "jim.admin":  {
+                "applicationId": "00000000-0000-0000-0000-000000000001",
+                "username": "jim.admin",
+                "name": "Jim Admin",
+                "email": "jim.admin@gmail.com",
+                "activated": true,
+                "disabled": false,
+                "uuid": "328b526e-cd0c-11e1-bcf8-12424d1c4491",
+                "adminUser": true,
+                "displayEmailAddress": "jim.admin <jim.admin@gmail.com>",
+                "htmldisplayEmailAddress": "jim.admin <<a href="mailto:jim.admin@gmail.com">jim.admin@gmail.com>"
+        },
+        ...
+        "adminUser": true,
+        "activated": true,
+        "name": "edort1",
+        "applicationId": "00000000-0000-0000-0000-000000000001",
+        "uuid": "328b526e-cd0c-11e1-bcf8-12424d1c4491",
+        "htmldisplayEmailAddress": "jim.admin <<a href="mailto:jim.admin@gmail.com">jim.admin@gmail.com>>",
+        "displayEmailAddress": "jim.admin <jim.admin@gmail.com>",
+        "disabled": false
+      },
+      "timestamp": 1349480786906,
+
+Setting an admin user's password
+--------------------------------
+
+Use the PUT method to update an admin user's password.
+
+### Request URI
+
+PUT
+/management/organizations/{org}/users/{user|username|email|uuid}/password
+{request body}
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter                            | Description                          |
++======================================+======================================+
+| string user|string username|string   | Admin username, name, email address, |
+| email|arg uuid                       | or UUID.                             |
++--------------------------------------+--------------------------------------+
+| request body                         | The password property and value:     |
+|                                      |                                      |
+|                                      |     {                                |
+|                                      |       "password": "test123"          |
+|                                      |     }                                |
++--------------------------------------+--------------------------------------+
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_set_admin_pw)
+-   [JavaScript (HTML5)](#javascript_set_admin_pw)
+-   [Ruby](#ruby_set_admin_pw)
+-   [Node.js](#nodejs_set_admin_pw)
+
+<!-- -->
+
+    curl -X -i PUT "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/password" -d '{"password":"test123"}'
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+ 
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org'
+    jim_admin = mgmt['users/jim.admin'].entity
+    jim_admin.password = 'test123'
+    jim_admin.save
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'PUT',
+        endpoint:'management/organizations/my-org/users/jim.admin',
+        body:{ password:'test123' }
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — PUT failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "set user password",
+      "timestamp": 1349714010142,
+      "duration": 0
+    }
+
+Resetting an admin user's password
+----------------------------------
+
+Resetting an admin user's password is a two step process. In the first
+step, you initiate the password reset. This returns a browser page. The
+page includes a field for the user to enter his or her email address,
+and a field to enter a response to a Captcha challenge. In the second
+step, you handle the user's responses from the form.
+
+### Initiating a password reset
+
+Use the GET method to initiate the password reset.
+
+### Request URI
+
+GET /management/organizations/{org}/users/resetpw
+
+### Example - Request
+
+-   [cURL](#curl_init_pw_reset)
+-   [JavaScript (HTML5)](#javascript_init_pw_reset)
+-   [Ruby](#ruby_init_pw_reset)
+-   [Node.js](#nodejs_init_pw_reset)
+
+<!-- -->
+
+    curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/resetpw"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    resetpw = mgmt['users/resetpw']
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'GET',
+        endpoint:'management/organizations/my-org/users/resetpw'
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — GET failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+    <html>
+    <head>
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+        <title>Reset Password</title>
+        <link rel="stylesheet" type="text/css" href="../../css/styles.css" />
+        <script type="text/javascript">>
+            var RecaptchaOptions = {
+                theme : 'clean'
+            };
+        </script>
+    </head>
+    <body>
+
+        <div class="dialog-area">
+            <div class="dialog-form-message">Incorrect Captcha, try again...</div>
+            <form class="dialog-form" action="" method="post">
+                <fieldset>
+                    <p>
+                        <label for="email">Please type your <strong>email
+                                address</strong> or <strong>username</strong> below.</label>
+                    </p>
+                    <p>
+                        <input class="text_field" id="email" name="email" type="text" />
+                    </p>
+                    <p id="human-proof"></p>
+                    <script type="text/javascript" src="https://www.google.com/recaptcha/api/challenge?k=6LdSTNESAAAAAKHdVglHmMu86_EoYxsJjqQD1IpZ"></script>
+
+                    <p class="buttons">
+                        <button type="submit">Submit</button>
+                    </p>
+                </fieldset>
+            </form>
+        </div>
+    </pre>
+
+### Completing a password reset
+
+Use the POST method to complete the password reset.
+
+### Request URI
+
+POST /management/organizations/{org}/users/resetpw {request body}
+
+### Parameters
+
++--------------------------------------+--------------------------------------+
+| Parameter                            | Description                          |
++======================================+======================================+
+| request body                         | Parameters and value for the Captcha |
+|                                      | challenge, the admin user's response |
+|                                      | to the Captcha challenge, and the    |
+|                                      | admin user's email address, for      |
+|                                      | example:                             |
+|                                      |                                      |
+|                                      |     {                                |
+|                                      |       "recaptcha_response_field" : " |
+|                                      | Atistophanes tseFia",                |
+|                                      |       "recaptcha_challenge_field" :  |
+|                                      | "Atistophanes tseFia",               |
+|                                      |       "email" : "jim.admin@gmail.com |
+|                                      | "                                    |
+|                                      |     }                                |
++--------------------------------------+--------------------------------------+
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_complete_pw_reset)
+-   [JavaScript (HTML5)](#javascript_complete_pw_reset)
+-   [Ruby](#ruby_complete_pw_reset)
+-   [Node.js](#nodejs_complete_pw_reset)
+
+<!-- -->
+
+    curl -X -i POST "https://api.usergrid.com/management/organizations/my-org/users/resetpw" -d '{"recaptcha_response_field":"Atistophanes tseFia","recaptcha_challenge_field":"Atistophanes tseFia","email":"jim.admin@gmail.com"}'
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+ 
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    resetpw = mgmt['users/resetpw']
+    resetpw { recaptcha_response_field: 'Atistophanes tseFia', recaptcha_challenge_field: 'Atistophanes tseFia', email: 'jim.admin@gmail.com' }
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'POST',
+        endpoint:'management/organizations/my-org/users/resetpw',
+        body:{ 
+           recaptcha_response_field:'Atistophanes tseFia', 
+           recaptcha_challenge_field:'Atistophanes tseFia', 
+           email:'jim.admin@gmail.com' 
+        }
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — POST failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "reset user password",
+      "timestamp": 13546154010321,
+      "duration": 0
+    }
+
+Activating an admin user
+------------------------
+
+Use the GET method to activate an admin user from a link provided in an
+email notification.
+
+### Request URI
+
+GET
+/management/organizations/{org}/users/{user|username|email|uuid}/activate?token={token}&confirm={confirm\_email}
+
+### Parameters
+
+  Parameter                                           Description
+  --------------------------------------------------- -------------------------------------------------
+  string user|string username|string email|arg uuid   Admin username, name, email address, or UUID.
+  string token                                        Activation token (supplied via email).
+  boolean confirm\_email                              Send confirmation email (false is the default).
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_activate_admin_user)
+-   [JavaScript (HTML5)](#javascript_activate_admin_user)
+-   [Ruby](#ruby_activate_admin_user)
+-   [Node.js](#nodejs_activate_admin_user)
+
+<!-- -->
+
+    curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/activate?token=33dd0563-cd0c-11e1-bcf7-12313d1c4491"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    mgmt['users/jim.admin/activate'].get params: { token: '33dd0563-cd0c-11e1-bcf7-12313d1c4491' }
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'GET',
+        endpoint:'management/organizations/my-org/users/jim.admin/activate',
+        qs:{token:'33dd0563-cd0c-11e1-bcf7-12313d1c4491'}
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — GET failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "activate user",
+      "timestamp": 1349718021324,
+      "duration": 0
+    }
+
+Reactivating an admin user
+--------------------------
+
+Use the GET method to reactivate an admin user.
+
+### Request URI
+
+GET
+/management/organizations/{org}/users/{user|username|email|uuid}/reactivate
+
+### Parameters
+
+  Parameter                                           Description
+  --------------------------------------------------- -----------------------------------------------
+  string user|string username|string email|arg uuid   Admin username, name, email address, or UUID.
+
+ 
+
+### Example - Request
+
+-   [cURL](#curl_reactivate_admin_user)
+-   [JavaScript (HTML5)](#javascript_reactivate_admin_user)
+-   [Ruby](#ruby_reactivate_admin_user)
+-   [Node.js](#nodejs_reactivate_admin_user)
+
+<!-- -->
+
+    curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/reactivate"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    mgmt['users/jim.admin/reactivate']
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'GET',
+        endpoint:'management/organizations/my-org/users/jim.admin/reactivate'
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — GET failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "reactivate user",
+      "timestamp": 1349735217217,
+      "duration": 3541
+    }
+
+Getting an admin user's activity feed
+-------------------------------------
+
+Use the GET method to retrieve an admin user's activity feed.
+
+### Request URI
+
+GET
+/management/organizations/{org}/users/{user|username|email|uuid}/feed
+
+### Parameters
+
+  Parameter                                           Description
+  --------------------------------------------------- -----------------------------------------------
+  string user|string username|string email|arg uuid   Admin username, name, email address, or UUID.
+
+### Example - Request
+
+-   [cURL](#curl_get_user_feed)
+-   [JavaScript (HTML5)](#javascript_get_user_feed)
+-   [Ruby](#ruby_get_user_feed)
+-   [Node.js](#nodejs_get_user_feed)
+
+<!-- -->
+
+    curl -X GET "https://api.usergrid.com/management/organizations/my-org/users/jim.admin/feed"
+
+It is recommended that you use the [Admin
+Portal](http://apigee.com/usergrid) for administrative activities
+instead of using JavaScript to do them programmatically in your app.
+
+**Note:**You can see the response below in the Admin Portal by using the
+[JavaScript
+Console](/docs/usergrid/content/displaying-app-services-api-calls-curl-commands).
+
+The example assumes use of the [Ruby
+SDK](https://github.com/scottganyo/usergrid_iron).
+
+    mgmt = Usergrid::Management.new 'https://api.usergrid.com/management/organizations/my-org/'
+    mgmt['users/jim.admin/feed'].get
+
+The example assumes use of the [Node.js
+module](https://github.com/apigee/usergrid-node-module).
+
+    var options = {
+        method:'GET',
+        endpoint:'management/organizations/my-org/users/jim.admin/feed'
+    };
+    client.request(options, function (err, data) {
+        if (err) {
+            //error — GET failed
+        } else {
+            //success — data will contain raw results from API call       
+        }
+    });
+
+### Example - Response
+
+    {
+      "action": "get admin user feed",
+      "status": "ok",
+     "entities":  [
+         {
+          "uuid": "cf3e981c-fe80-11e1-95c8-12331b144c65",
+          "type": "activity",
+          "created": 1347643370454,
+          "modified": 1347643370454,
+          "actor":  {
+            "displayName": "jim.admin",
+            "objectType": "person",
+            "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591",
+            "entityType": "user"
+          },
+          "category": "admin",
+          "metadata":  {
+            "cursor": "gGkAAQMAgGkABgE5xc3r1gCAdQAQz02YHP6QEeGVyBIxOxIsVgCAdQAQz4ZbYf6QEeGVyBIxOxIsVgA",
+            "path": "/users/327b527f-cd0c-11e1-bcf7-12313d1c4491/feed/cf4d981c-fe90-11e1-95c8-12313b122c56"
+          },
+        "object":  {
+        ...
+        },
+        "published": 1342198809251,
+                "title": "<a mailto="jim.admingmail.com">jim.admin (jim.admin@gmail.com)</a> created a new organization account named jim.admin",
+                "verb": "create"
+              }
+            ],
+      "timestamp": 1349735719320,

Added: incubator/usergrid/site/content/docs/app-security.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/app-security.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/app-security.md (added)
+++ incubator/usergrid/site/content/docs/app-security.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,42 @@
+---
+title: App security
+category: docs
+layout: docs
+---
+
+App security
+============
+
+Any app you put into production should feature security that protects
+your app, your users, and your app's data. Implementing security means
+taking steps in your mobile app's code and in your Apache Usergrid
+application.
+
+> **Important:** When you register for Apache Usergrid, you get a sandbox
+> application that you can use to try things out. This application is
+> not for use in production. By default, the sandbox application is not
+> protected by any security measures whatsoever. Use the sandbox only
+> for experimentation, and only with data that isn't in any way
+> sensitive.
+
+When securing your app, follow these high-level steps:
+
+1.  Define the rules that will govern access by your app's users to your
+    app's data and features. You do this with the admin portal by
+    creating permission rules, then associating those rules with your
+    users. For more information, see [Managing access by defining
+    permission rules](/managing-access-defining-permission-rules).
+2.  Write code through which your app's users can verify who they are to
+    your Apache Usergrid application. You do this by writing code that uses
+    their username and password as credentials to initially authenticate
+    with the Apache Usergrid application, then uses a token thereafter.
+    (This authentication style supports the OAuth 2.0 model.) For more
+    information, see [Authenticating users and application
+    clients](/authenticating-users-and-application-clients).
+3.  Be sure to use coding best practices that help ensure that your app
+    is protected from malicious attacks. For more information, see
+    [Securing your app](/securing-your-app).
+
+The following illustration describes these high-level areas.
+
+![](/docs/sites/docs/files/styles/large/public/security_model_0.png?itok=_fErNYbL)

Added: incubator/usergrid/site/content/docs/application.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/application.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/application.md (added)
+++ incubator/usergrid/site/content/docs/application.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,90 @@
+---
+title: Application
+category: docs
+layout: docs
+---
+
+Application
+===========
+
+You can create a new application in an organization through the [Admin
+portal](/admin-portal). The Admin portal creates the new application by
+issuing a post against the management endpoint (see the "Creating an
+organization application" section in [Organization](/organization) for
+details). If you need to create an application programmatically in your
+app, you can also use the API to do this. You can access application
+entities using your app name or UUID, prefixed with the organization
+name or UUID:
+
+[https://api.usergrid.com](http://api.usergrid.com/)/{org\_name|uuid}/{app\_name|uuid}
+
+Most mobile apps never access the application entity directly. For
+example you might have a server-side web app that accesses the
+application entity for configuration purposes. If you want to access
+your application entity programmatically, you can use the API.
+
+Application properties
+----------------------
+
+The following are the system-defined properties for application
+entities. You can create application-specific properties for an
+application entity in addition to the system-defined properties. The
+system-defined properties are reserved. You cannot use these names to
+create other properties for an application entity. In addition the
+applications name is reserved for the applications collection — you
+can't use it to name another collection.
+
+The look-up properties for the entities of type application are uuid and
+name, that is, you can use the uuid and name properties to reference an
+application entity in an API call. However, you can search on a role
+using any property of the application entity. See [Queries and
+parameters](/queries-and-parameters) for details on searching.
+
+  Property                                Type      Description
+  --------------------------------------- --------- ---------------------------------------------------------------------------------
+  uuid                                    UUID      Application’s unique entity ID
+  type                                    string    "application"
+  created                                 long      [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+  modified                                long      [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+  name                                    string    Application name (mandatory)
+  title                                   string    Application title
+  description                             string    Application description
+  activated                               boolean   Whether application is activated
+  disabled                                boolean   Whether application is administratively disabled
+  allowOpenRegistration                   boolean   Whether application allows any user to register
+  registrationRequiresEmailConfirmation   boolean   Whether registration requires email confirmation
+  registrationRequiresAdminApproval       boolean   Whether registration requires admin approval
+  accesstokenttl                          long      Time to live value for an access token obtained within the application
+
+Set properties
+--------------
+
+The set properties for applications are listed in the table below.
+
+  Set              Type     Description
+  ---------------- -------- ----------------------------------------------------
+  collections      string   Set of collections
+  rolenames        string   Set of roles assigned to an application
+  counters         string   Set of counters assigned to an application
+  oauthproviders   string   Set of OAuth providers for the application
+  credentials      string   Set of credentials required to run the application
+
+Collections
+-----------
+
+The collections for applications are listed in the table below.
+
+  Collection      Type           Description
+  --------------- -------------- ----------------------------------------------------------------------------------
+  users           user           Collection of users
+  groups          group          Collection of groups
+  folders         folder         Collection of assets that represent folder-like objects
+  events          event          Collection of events posted by the application
+  assets          asset          Collection of assets that represent file-like objects
+  activities      activity       Collection of activity stream actions
+  devices         device         Collection of devices in the service
+  notifiers       notifier       Collection of notifiers used for push notifications
+  notifications   notification   Collection of push notifications that have been sent or are scheduled to be sent
+  receipts        receipt        Collection of receipts from push notifications that were sent
+
+ 

Added: incubator/usergrid/site/content/docs/applications.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/applications.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/applications.md (added)
+++ incubator/usergrid/site/content/docs/applications.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,85 @@
+---
+title: Applications
+category: docs
+layout: docs
+---
+
+Applications
+------------
+
+You can create a new application in an organization through the [Admin
+portal](/admin-portal). The Admin portal creates the new application by
+issuing a post against the management endpoint (see the "Creating an
+organization application" section in [Organization](/organization) for
+details). If you need to create an application programmatically in your
+app, you can also use the API to do this. You can access application
+entities using your app name or UUID, prefixed with the organization
+name or UUID:
+
+[https://api.usergrid.com](http://api.usergrid.com/)/{org\_name|uuid}/{app\_name|uuid}
+
+Most mobile apps never access the application entity directly. For
+example you might have a server-side web app that accesses the
+application entity for configuration purposes. If you want to access
+your application entity programmatically, you can use the API.
+
+### Application properties
+
+The following are the system-defined properties for application
+entities. You can create application-specific properties for an
+application entity in addition to the system-defined properties. The
+system-defined properties are reserved. You cannot use these names to
+create other properties for an application entity. In addition the
+applications name is reserved for the applications collection — you
+can't use it to name another collection.
+
+The look-up properties for the entities of type application are uuid and
+name, that is, you can use the uuid and name properties to reference an
+application entity in an API call. However, you can search on a role
+using any property of the application entity. See [Queries and
+parameters](/queries-and-parameters) for details on searching.
+
+  Property                                Type      Description
+  --------------------------------------- --------- ---------------------------------------------------------------------------------
+  uuid                                    UUID      Application’s unique entity ID
+  type                                    string    "application"
+  created                                 long      [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+  modified                                long      [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+  name                                    string    Application name (mandatory)
+  title                                   string    Application title
+  description                             string    Application description
+  activated                               boolean   Whether application is activated
+  disabled                                boolean   Whether application is administratively disabled
+  allowOpenRegistration                   boolean   Whether application allows any user to register
+  registrationRequiresEmailConfirmation   boolean   Whether registration requires email confirmation
+  registrationRequiresAdminApproval       boolean   Whether registration requires admin approval
+  accesstokenttl                          long      Time to live value for an access token obtained within the application
+
+### Set properties
+
+The set properties for applications are listed in the table below.
+
+  Set              Type     Description
+  ---------------- -------- ----------------------------------------------------
+  collections      string   Set of collections
+  rolenames        string   Set of roles assigned to an application
+  counters         string   Set of counters assigned to an application
+  oauthproviders   string   Set of OAuth providers for the application
+  credentials      string   Set of credentials required to run the application
+
+### Collections
+
+The collections for applications are listed in the table below.
+
+  Collection      Type           Description
+  --------------- -------------- ----------------------------------------------------------------------------------
+  users           user           Collection of users
+  groups          group          Collection of groups
+  folders         folder         Collection of assets that represent folder-like objects
+  events          event          Collection of events posted by the application
+  assets          asset          Collection of assets that represent file-like objects
+  activities      activity       Collection of activity stream actions
+  devices         device         Collection of devices in the service
+  notifiers       notifier       Collection of notifiers used for push notifications
+  notifications   notification   Collection of push notifications that have been sent or are scheduled to be sent
+  receipts        receipt        Collection of receipts from push notifications that were sent
\ No newline at end of file

Added: incubator/usergrid/site/content/docs/assets.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/assets.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/assets.md (added)
+++ incubator/usergrid/site/content/docs/assets.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,46 @@
+---
+title: Assets
+category: docs
+layout: docs
+---
+
+Asset entities are used primarily in Apache Usergrid to manage binary data
+objects such as images, video, and audio content. However, an asset does
+not have to be used for a binary object. For example, assets can be used
+to model a file system.
+
+Using App services APIs you can create, retrieve, update, delete, and
+query asset entities. See You do not have access to view this node for
+descriptions of these APIs.
+
+Asset properties
+----------------
+
+The following are the system-defined properties for asset entities. You
+can create application-specific properties for an asset entity in
+addition to the system-defined properties. The system-defined properties
+are reserved. You cannot use these names to create other properties for
+an asset entity. In addition the assets name is reserved for the assets
+collection — you can't use it to name another collection.
+
+  Property       Type     Description
+  -------------- -------- ---------------------------------------------------------------------------------
+  uuid           UUID     Asset’s unique entity ID
+  type           string   "asset"
+  name           string   Asset name (mandatory)
+  created        long     [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
+  modified       long     [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
+  owner          UUID     UUID of the asset’s owner (mandatory)
+  path           string   Relative path to the asset (mandatory)
+  content-type   string   Content type of the asset (for example, “image/jpeg”)
+
+Set property
+------------
+
+Assets have the following set property.
+
+  Set           Type     Description
+  ------------- -------- ----------------------------------
+  connections   string   Set of connections for the asset
+
+ 

Added: incubator/usergrid/site/content/docs/authenticating-users-and-application-clients.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/authenticating-users-and-application-clients.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/authenticating-users-and-application-clients.md (added)
+++ incubator/usergrid/site/content/docs/authenticating-users-and-application-clients.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,485 @@
+---
+title: Authenticating users and application clients
+category: docs
+layout: docs
+---
+
+Authenticating users and application clients
+============================================
+
+To protect your Apache Usergrid application data, one of the steps you'll
+take is to authenticate your app's users. By ensuring that they are who
+they say they are, you can help ensure that your application's data is
+available in secure ways. After you've created permission rules that
+define access to your application and have associated these rules with
+users, you'll want to add code that authenticates your user, as
+described in this topic.
+
+**Note: **You manage access to your application's data by creating
+permission rules that govern which users can do what. Users
+authenticated as Application User have access according to these rules.
+For more about managing permissions, see [Managing access by defining
+permission rules](/managing-access-defining-permission-rules).
+
+Authentication levels
+---------------------
+
+Apache Usergrid supports four levels of authentication, but only one of
+them is used when checking a registered user's permissions. The other
+three levels are useful for authenticating other web applications that
+want to access to your Apache Usergrid application. Because the scope of
+access that the other authentication levels provide is so broad (and as
+a result, so powerful), it's a bad practice to use them from a mobile
+app. Instead, they're better suited to other client apps, such as web
+applications.
+
+The following table describes each of the authentication levels. Note
+that only one of these is configurable using the admin portal. The
+others are independent of Application User level access, which is
+governed by permission rules you define (usually with the admin portal).
+In contrast, the level of acces provided by the others is only as
+described in the notes.
+
++--------------------+--------------------+--------------------+--------------------+
+| Authentication     | Description        | Permissions        | Notes              |
+| Level              |                    | Configurable in    |                    |
+|                    |                    | Admin Portal       |                    |
++====================+====================+====================+====================+
+| Application User   | Allows access to   | Yes                | You allow specific |
+|                    | your Apache Usergrid  |                    | access to          |
+|                    | application as     |                    | application        |
+|                    | governed by the    |                    | resources by       |
+|                    | permission rules   |                    | creating           |
+|                    | you create and     |                    | permission rules,  |
+|                    | associated with    |                    | then associating   |
+|                    | users and user     |                    | these rules with   |
+|                    | groups.            |                    | users. Typically,  |
+|                    |                    |                    | you'll begin by    |
+|                    |                    |                    | creating roles,    |
+|                    |                    |                    | then create        |
+|                    |                    |                    | permission rules   |
+|                    |                    |                    | for the roles,     |
+|                    |                    |                    | then associate the |
+|                    |                    |                    | roles with users   |
+|                    |                    |                    | (or groups of      |
+|                    |                    |                    | users).            |
+|                    |                    |                    |                    |
+|                    |                    |                    | Each Application   |
+|                    |                    |                    | User is            |
+|                    |                    |                    | represented by a   |
+|                    |                    |                    | User entity in     |
+|                    |                    |                    | your Apache Usergrid  |
+|                    |                    |                    | application. (For  |
+|                    |                    |                    | more about the     |
+|                    |                    |                    | User entity, see   |
+|                    |                    |                    | [User](/user).)    |
+|                    |                    |                    |                    |
+|                    |                    |                    | For more about     |
+|                    |                    |                    | roles and          |
+|                    |                    |                    | permissions, see   |
+|                    |                    |                    | [Managing access   |
+|                    |                    |                    | by defining        |
+|                    |                    |                    | permission         |
+|                    |                    |                    | rules](/managing-a |
+|                    |                    |                    | ccess-defining-per |
+|                    |                    |                    | mission-rules).    |
+|                    |                    |                    | For a look at how  |
+|                    |                    |                    | security features  |
+|                    |                    |                    | fit together, see  |
+|                    |                    |                    | [App Security      |
+|                    |                    |                    | Overview](/app-sec |
+|                    |                    |                    | urity-overview).   |
++--------------------+--------------------+--------------------+--------------------+
+| Application        | Allows full access | No                 | Authentication at  |
+|                    | to perform any     |                    | this level is      |
+|                    | operation on an    |                    | useful in a        |
+|                    | Apache Usergrid       |                    | server-side        |
+|                    | application        |                    | application (not a |
+|                    | account (but not   |                    | mobile app) that   |
+|                    | other applications |                    | needs access to    |
+|                    | within the same    |                    | resources through  |
+|                    | organization).     |                    | the Apache Usergrid   |
+|                    | Should not be used |                    | API.               |
+|                    | from a mobile      |                    |                    |
+|                    | client.            |                    | Imagine that you   |
+|                    |                    |                    | created a web site |
+|                    |                    |                    | that lists every   |
+|                    |                    |                    | hiking trail in    |
+|                    |                    |                    | the Rocky          |
+|                    |                    |                    | Mountains. Anyone  |
+|                    |                    |                    | can go to the web  |
+|                    |                    |                    | site and view the  |
+|                    |                    |                    | content. However,  |
+|                    |                    |                    | you don't want     |
+|                    |                    |                    | anyone to have     |
+|                    |                    |                    | access to the App  |
+|                    |                    |                    | Services API,      |
+|                    |                    |                    | where all the data |
+|                    |                    |                    | is stored. But you |
+|                    |                    |                    | do want to give    |
+|                    |                    |                    | your web server    |
+|                    |                    |                    | access so that it  |
+|                    |                    |                    | can generate the   |
+|                    |                    |                    | pages to serve to  |
+|                    |                    |                    | the website’s      |
+|                    |                    |                    | visitors.          |
+|                    |                    |                    |                    |
+|                    |                    |                    | **Warning:** You   |
+|                    |                    |                    | should never       |
+|                    |                    |                    | authenticate this  |
+|                    |                    |                    | way from a         |
+|                    |                    |                    | client-side app    |
+|                    |                    |                    | such as a mobile   |
+|                    |                    |                    | app. A hacker      |
+|                    |                    |                    | could analyze your |
+|                    |                    |                    | app and extract    |
+|                    |                    |                    | the credentials    |
+|                    |                    |                    | for malicious use  |
+|                    |                    |                    | even if those      |
+|                    |                    |                    | credentials are    |
+|                    |                    |                    | compiled and in    |
+|                    |                    |                    | binary format. See |
+|                    |                    |                    | [Safe mobile       |
+|                    |                    |                    | access](#safe_mobi |
+|                    |                    |                    | le)                |
+|                    |                    |                    | for additional     |
+|                    |                    |                    | considerations in  |
+|                    |                    |                    | keeping access to  |
+|                    |                    |                    | your app and its   |
+|                    |                    |                    | data secure.       |
++--------------------+--------------------+--------------------+--------------------+
+| Admin User         | Allows full access | No                 | This               |
+|                    | to perform any     |                    | authentication     |
+|                    | operation on all   |                    | level is useful    |
+|                    | organization       |                    | from applications  |
+|                    | accounts of which  |                    | that provide       |
+|                    | the admin user is  |                    | organization-wide  |
+|                    | a member. Should   |                    | administration     |
+|                    | not be used from a |                    | features. For      |
+|                    | mobile client.     |                    | example, the App   |
+|                    |                    |                    | Services admin     |
+|                    |                    |                    | portal uses this   |
+|                    |                    |                    | level of access    |
+|                    |                    |                    | because it         |
+|                    |                    |                    | requires full      |
+|                    |                    |                    | access to the      |
+|                    |                    |                    | administration     |
+|                    |                    |                    | features.          |
+|                    |                    |                    |                    |
+|                    |                    |                    | Unless you have a  |
+|                    |                    |                    | specific need for  |
+|                    |                    |                    | administrative     |
+|                    |                    |                    | features, such as  |
+|                    |                    |                    | to run test        |
+|                    |                    |                    | scripts that       |
+|                    |                    |                    | require access to  |
+|                    |                    |                    | management         |
+|                    |                    |                    | functionality, you |
+|                    |                    |                    | should not use the |
+|                    |                    |                    | admin user         |
+|                    |                    |                    | authentication     |
+|                    |                    |                    | level.             |
+|                    |                    |                    |                    |
+|                    |                    |                    | **Note:**          |
+|                    |                    |                    | Currently,         |
+|                    |                    |                    | organization and   |
+|                    |                    |                    | admin user access  |
+|                    |                    |                    | are effectively    |
+|                    |                    |                    | the same.          |
+|                    |                    |                    | Eventually, the    |
+|                    |                    |                    | admin user level   |
+|                    |                    |                    | will be a          |
+|                    |                    |                    | configurable       |
+|                    |                    |                    | subset of the      |
+|                    |                    |                    | organization level |
+|                    |                    |                    | of access.         |
+|                    |                    |                    | **Warning:** You   |
+|                    |                    |                    | should never       |
+|                    |                    |                    | authenticate this  |
+|                    |                    |                    | way from a         |
+|                    |                    |                    | client-side app    |
+|                    |                    |                    | such as a mobile   |
+|                    |                    |                    | app. A hacker      |
+|                    |                    |                    | could analyze your |
+|                    |                    |                    | app and extract    |
+|                    |                    |                    | the credentials    |
+|                    |                    |                    | for malicious use  |
+|                    |                    |                    | even if those      |
+|                    |                    |                    | credentials are    |
+|                    |                    |                    | compiled and in    |
+|                    |                    |                    | binary format. See |
+|                    |                    |                    | [Safe mobile       |
+|                    |                    |                    | access](#safe_mobi |
+|                    |                    |                    | le)                |
+|                    |                    |                    | for additional     |
+|                    |                    |                    | considerations in  |
+|                    |                    |                    | keeping access to  |
+|                    |                    |                    | your app and its   |
+|                    |                    |                    | data secure.       |
++--------------------+--------------------+--------------------+--------------------+
+| Organization       | Full access to     | No                 | Providing the      |
+|                    | perform any        |                    | greatest amount of |
+|                    | operation on an    |                    | access, this       |
+|                    | Apache Usergrid       |                    | authentication     |
+|                    | organization.      |                    | level lets a       |
+|                    | Should not be used |                    | client perform any |
+|                    | from a mobile      |                    | operation on an    |
+|                    | client.            |                    | Apache Usergrid       |
+|                    |                    |                    | organization. This |
+|                    |                    |                    | level of access    |
+|                    |                    |                    | should be used     |
+|                    |                    |                    | sparingly and      |
+|                    |                    |                    | carefully.         |
+|                    |                    |                    |                    |
+|                    |                    |                    | **Note:**          |
+|                    |                    |                    | Currently,         |
+|                    |                    |                    | organization and   |
+|                    |                    |                    | admin user access  |
+|                    |                    |                    | are effectively    |
+|                    |                    |                    | the same.          |
+|                    |                    |                    | Eventually, the    |
+|                    |                    |                    | admin user level   |
+|                    |                    |                    | will be a          |
+|                    |                    |                    | configurable       |
+|                    |                    |                    | subset of the      |
+|                    |                    |                    | organization level |
+|                    |                    |                    | of access.         |
+|                    |                    |                    | **Warning:** You   |
+|                    |                    |                    | should never       |
+|                    |                    |                    | authenticate this  |
+|                    |                    |                    | way from a         |
+|                    |                    |                    | client-side app    |
+|                    |                    |                    | such as a mobile   |
+|                    |                    |                    | app. A hacker      |
+|                    |                    |                    | could analyze your |
+|                    |                    |                    | app and extract    |
+|                    |                    |                    | the credentials    |
+|                    |                    |                    | for malicious use  |
+|                    |                    |                    | even if those      |
+|                    |                    |                    | credentials are    |
+|                    |                    |                    | compiled and in    |
+|                    |                    |                    | binary format. See |
+|                    |                    |                    | [Safe mobile       |
+|                    |                    |                    | access](#safe_mobi |
+|                    |                    |                    | le)                |
+|                    |                    |                    | for additional     |
+|                    |                    |                    | considerations in  |
+|                    |                    |                    | keeping access to  |
+|                    |                    |                    | your app and its   |
+|                    |                    |                    | data secure.       |
++--------------------+--------------------+--------------------+--------------------+
+
+Adding code to support authentication
+-------------------------------------
+
+### Using an access token
+
+When you obtain an access token, you must provide it with every
+subsequent API call that you make. There are two ways to provide your
+access token.
+
+-   You can add the token to the API query string:\
+    \
+
+        https://api.usergrid.com/{org-name}/{app-name}/users?access_token={access_token}
+
+-   You can include the token in an HTTP authorization header:\
+    \
+
+        Authorization: Bearer {access_token}
+
+**Note:** The App services documentation assumes you are providing a
+valid access token with every API call whether or not it is shown
+explicitly in the examples. Unless the documentation specifically says
+that you can access an API endpoint without an access token, you should
+assume that you must provide it. One application that does not require
+an access token is the sandbox application. The Guest role has been
+given full permissions (/\*\* for GET, POST, PUT, and DELETE) for this
+application. This eliminates the need for a token when making
+application level calls to the sandbox app. For further information on
+specifying permissions, see [Managing access by defining permission
+rules](/managing-access-defining-permission-rules).
+
+### Authenticating as Application User
+
+Using the username and password values specified when the user entity
+was created, your app can connect to the Apache Usergrid application
+endpoint to request an access token. (Note that it's also possible to
+use the user's email address in place of the username.) Here is an
+example in cURL format of a request for application user access:
+
+    curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token" -d '{"grant_type":"password","username":"john.doe","password":"testpw"}'
+
+The results include the access token needed to make subsequent API
+requests on behalf of the application user:
+
+    {
+    "access_token": "5wuGd-lcEeCUBwBQVsAACA:F8zeMOlcEeCUBwBQVsAACA:YXU6AAABMq0hdy4Lh0ewmmnOWOR-DaepCrpWx9oPmw",
+    "expires_in": 3600,
+    "user": {
+    ...
+    }
+    }
+        
+
+### Authenticating as Application
+
+Using your app’s client id and client secret values, your app can
+connect to the Apache Usergrid application endpoint to request an access
+token. Here is an example in cURL format of a request for application
+access:
+
+    curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'
+
+The results include the access token needed to make subsequent API
+requests on behalf of the application:
+
+    {
+    "access_token": "F8zeMOlcEeCUBwBQVsAACA:YXA6AAABMq0d4Mep_UgbZA0-sOJRe5yWlkq7JrDCkA",
+    "expires_in": 3600,
+    "application": {
+    ...  
+    }
+    }
+        
+
+**Warning:** You should never authenticate this way from a client-side
+app such as a mobile app. A hacker could analyze your app and extract
+the credentials for malicious use even if those credentials are compiled
+and in binary format. See [Safe mobile access](#safe_mobile) for
+additional considerations in keeping access to your app and its data
+secure.
+
+### Authenticating as Admin User
+
+If you do require admin user access, your app can connect to the App
+Services management endpoint to request an access token. Your app
+supplies the username and password of an admin user in the request. Here
+is an example in cURL format of a request for admin user access:
+
+    curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token"  -d '{"grant_type":"password","username":"testadmin","password":"testadminpw"}'
+
+The results include the access token needed to make subsequent API
+requests on behalf of the admin user:
+
+    {
+    "access_token": "f_GUbelXEeCfRgBQVsAACA:YWQ6AAABMqz_xUyYeErOkKjnzN7YQXXlpgmL69fvaA",
+    "expires_in": 3600,
+    "user": {
+    ...
+    }
+    }
+        
+
+**Warning:** You should never authenticate this way from a client-side
+app such as a mobile app. A hacker could analyze your app and extract
+the credentials for malicious use even if those credentials are compiled
+and in binary format. See [Safe mobile access](#safe_mobile) for
+additional considerations in keeping access to your app and its data
+secure.
+
+### Authenticating as Organization
+
+If you do require organization level access, your app can connect to the
+Apache Usergrid management endpoint to request an access token. Access to
+an organization requires the client id and client secret credentials.
+Here is an example in cURL format of a request for organization access:
+
+    curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'
+
+The results include the access token needed to make subsequent API
+requests to the organization:
+
+    {
+    "access_token": "gAuFEOlXEeCfRgBQVsAACA:b3U6AAABMqz-Cn0wtDxxkxmQLgZvTMubcP20FulCZQ",
+    "expires_in": 3600,
+    "organization": {
+    ...
+    }
+    }
+        
+
+**Warning:** You should never authenticate this way from a client-side
+app such as a mobile app. A hacker could analyze your app and extract
+the credentials for malicious use even if those credentials are compiled
+and in binary format. See [Safe mobile access](#safe_mobile) for
+additional considerations in keeping access to your app and its data
+secure.
+
+Authentication token time to live
+---------------------------------
+
+An access token has a “time-to-live”, which is the maximum time that the
+access token will be valid for use within the application, specified in
+milliseconds. By default, all tokens have a system-defined time-to-live
+of 24 hours.
+
+### Changing the default time-to-live
+
+You can change the default time-to-live for all application tokens by
+updating the Application entity’s accesstokenttl property. 
+
+For example, the following updates an application entity to have a
+default time-to-live value of 1800000 miliseconds (30 minutes) for all
+tokens:
+
+    curl -X PUT -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app" -d '{"accesstokenttl":"1800000"}'
+
+### Changing token time-to-live
+
+When you request an access token, you can override its time-to-live by
+including a ttl parameter in the request.
+
+The ttl value must be equal to or less than the value of the
+accesstokenttl property. If you specify a ttl value greater than the
+value of accesstokenttl, an error message is returned that indicates the
+maximum time to live value that can be specified.
+
+**Note: **If you set ttl=0, the token will never expire. This can pose a
+security risk and should be used with caution.
+
+For example, the following sets a time to live value of 1800000
+miliseconds (30 minutes) for an admin user:
+
+    curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token?ttl=1800000" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'
+
+The following sets the same time to live value for an application user.
+
+    curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token?ttl=1800000" -d '{"grant_type":"password","username":"testadmin","password":"testadminpw"}'
+
+Revoking authentication tokens
+------------------------------
+
+Under certain circumstances, you may need to explicitly revoke a user's
+access token, such as when a user logs out. To revoke a specific
+authentication token, send the following `PUT` request:
+
+    curl -X PUT https://api.usergrid.com/<org_name>/<app_name>/users/<user_uuid_or_username>/revoketokens?token="<token>"
+
+If the token is successfully revoked, you will receive the following
+response from the API:
+
+    {
+      "action" : "revoked user token",
+      "timestamp" : 1382050891455,
+      "duration" : 24
+    }
+
+Safe mobile access
+------------------
+
+For mobile access, it is recommended that you connect as an application
+user with configured access control policies. Mobile applications are
+inherently untrusted because they can be easily examined and even
+decompiled.
+
+Any credentials stored in a mobile app should be considered secure only
+to the Application User level. This means that if you don’t want the
+user to be able to access or delete data in your Apache Usergrid
+application, you need to make sure that you don’t enable that capability
+through roles or permissions. Because most web applications talk to the
+database using some elevated level of permissions, such as root, it’s
+generally a good idea for mobile applications to connect with a more
+restricted set of permissions. For more information on restricting
+access through permission rules, see [Managing access by defining
+permission rules](/managing-access-defining-permission-rules).

Added: incubator/usergrid/site/content/docs/authentication-and-access-app-services-0.md
URL: http://svn.apache.org/viewvc/incubator/usergrid/site/content/docs/authentication-and-access-app-services-0.md?rev=1543106&view=auto
==============================================================================
--- incubator/usergrid/site/content/docs/authentication-and-access-app-services-0.md (added)
+++ incubator/usergrid/site/content/docs/authentication-and-access-app-services-0.md Mon Nov 18 18:51:18 2013
@@ -0,0 +1,271 @@
+---
+title: Authentication and access in App services
+category: docs
+layout: docs
+---
+
+Authentication and access in App services
+=========================================
+
+App services requests are authenticated via OAuth (Open Authorization)
+2.0. OAuth is an authentication mechanism that allows users to grant
+access to their web resources or mobile apps safely, without having to
+share their passwords. The analogy of a valet key is sometimes used to
+describe OAuth, because users can permit general access, but limit
+access rights to perform certain operations. Instead of an app user
+having to share a password, OAuth enables access using a security token
+tied specifically to an app and device.
+
+Unlike OAuth 1.0, which requires special support in the client code for
+signing requests, OAuth 2.0 can be used by any web service client
+libraries. Although the OAuth 2.0 specification isn’t finalized yet, it
+is sufficiently complete so that many web service providers, including
+Google and Facebook, are now using it for authentication. More
+information about OAuth 2.0 is available at
+[oauth.net](http://oauth.net/2/).
+
+Access types
+------------
+
+App services take advantage of standard OAuth 2.0 mechanisms that
+require an access token with data operation requests. To obtain the
+access token, you connect to an appropriate web service endpoint and
+provide the correct client credentials. The credentials required to get
+the token depend on the type of access you need.
+
+There are four access types.
+
+  Access Type        Description
+  ------------------ -------------------------------------------------------------------------------------------------------
+  Organization       Full access to perform any operation on a App services organization account
+  Admin User         Full access to perform any operation on all organization accounts of which the admin user is a member
+  Application        Full access to perform any operation on a App services application account
+  Application User   Policy-limited access to perform operations on a App services application account
+
+The *Organization* and *Application* access types are intended for
+server-side applications because they are "superuser" access mechanisms
+with few constraints on what they are permitted to do. When connecting
+via OAuth, you supply organization or application client ID and client
+secret parameters as client credentials. The Home page of the developer
+portal shows these parameters for the organization, while the Settings
+page displays them for the currently selected app.
+
+The *Admin User* and *Application User* access types are appropriate for
+connections on behalf of a known user account, such as an admin user who
+is a member of several organizations and has management rights to
+several apps, or an application user authorized for an application. When
+connecting via OAuth on behalf of a known user, you supply username and
+password parameters as client credentials.
+
+Each access type is discussed below, along with information on supplying
+an access token in an API request.
+
+### Organizations
+
+When you sign up for the App services developer portal, you create an
+organization account in addition to your personal admin user account.
+Access to a single organization requires client ID and client secret
+credentials (or an admin user can supply username and password
+credentials, as shown in the next section).
+
+As an example of accessing an organization, you can obtain your client
+ID and client secret values from the developer portal and connect to the
+following URL (substituting the correct values for \<client\_id\> and
+\<client\_secret\>):
+
+    https://api.usergrid.com/management/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>
+
+The results show the access token needed to make subsequent API
+requests, as well as additional information about the organization:
+
+    {
+      "access_token": "gAuFEOlXEeCfRgBQVsAACA:b3U6AAABMqz-Cn0wtDxxkxmQLgZvTMubcP20FulCZQ",
+      "expires_in": 3600,
+      "organization": {
+        "users": {
+          "test": {
+            "name": "Test User",
+            "disabled": false,
+            "uuid": "7ff1946d-e957-11e0-9f46-005056c00008",
+            "activated": true,
+            "username": "test",
+            "applicationId": "00000000-0000-0000-0000-000000000001",
+            "email": "test@usergrid.com",
+            "adminUser": true,
+            "mailTo": "Test User <test@usergrid.com>"
+          }
+        },
+        "name": "test-organization",
+        "applications": {
+          "test-app": "8041893b-e957-11e0-9f46-005056c00008"
+        },
+        "uuid": "800b8510-e957-11e0-9f46-005056c00008"
+      }
+    }
+
+### Admin users
+
+*Admin Users* are users of the Usergrid.com service as well as members
+of one or more organizations. In turn, an organization can have one or
+more admin users. Currently all admin users in an organization have full
+access permissions after they authenticate using their basic username
+and password credentials. In a subsequent release, App services will
+support a more fine-grained, delegated administration model in which
+access rights for admin users are configurable.
+
+As an example. to authenticate as an admin user, use the username and
+password values specified when you created your admin user account and
+connect to the following URL (substituting the correct values for
+\<username\> and \<password\>):
+
+    https://api.usergrid.com/management/token?grant_type=password&username=<username>&password=<password>
+
+In these results, note the access token needed to make subsequent API
+requests on behalf of the admin user:
+
+    {
+      "access_token": "f_GUbelXEeCfRgBQVsAACA:YWQ6AAABMqz_xUyYeErOkKjnzN7YQXXlpgmL69fvaA",
+      "expires_in": 3600,
+      "user": {
+        "username": "test",
+        "email": "test@usergrid.com",
+        "organizations": {
+          "test-organization": {
+            "users": {
+              "test": {
+                "name": "Test User",
+                "disabled": false,
+                "uuid": "7ff1946d-e957-11e0-9f46-005056c00008",
+                "activated": true,
+                "username": "test",
+                "applicationId": "00000000-0000-0000-0000-000000000001",
+                "email": "test@usergrid.com",
+                "adminUser": true,
+                "mailTo": "Test User <test@usergrid.com>"
+              }
+            },
+            "name": "test-organization",
+            "applications": {
+              "test-app": "8041893b-e957-11e0-9f46-005056c00008"
+            },
+            "uuid": "800b8510-e957-11e0-9f46-005056c00008"
+          }
+        },
+        "adminUser": true,
+        "activated": true,
+        "name": "Test User",
+        "mailTo": "Test User <test@usergrid.com>",
+        "applicationId": "00000000-0000-0000-0000-000000000001",
+        "uuid": "7ff1946d-e957-11e0-9f46-005056c00008",
+        "disabled": false
+      }
+    }
+
+Applications
+------------
+
+Users can access applications in three ways:
+
+-   With application client ID and client secret credentials
+-   With the client ID and client secret credentials of the organization
+    that owns the application
+-   With username and password credentials of an admin user associated
+    with the application’s organization
+
+Using your client ID and client secret values (obtained from the
+Application Settings section of the developer portal), you can connect
+to the following URL (substituting the correct values for
+\<org-name\>,\<app-name\>, \<client\_id\>, and \<client\_secret\>):
+
+    https://api.usergrid.com/<org-name>/<app-name>/token?grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>
+
+The results show the access token needed to make subsequent API requests
+on behalf of the application:
+
+    {
+      "access_token": "F8zeMOlcEeCUBwBQVsAACA:YXA6AAABMq0d4Mep_UgbZA0-sOJRe5yWlkq7JrDCkA",
+      "expires_in": 3600,
+      "application": {
+        "name": "test-app",
+        "id": "17ccde30-e95c-11e0-9407-005056c00008"
+      }
+    }
+
+Application users
+-----------------
+
+*Application Users* are members of the "users" collection within an
+application. They are the actual users of an app and their data is
+stored separately from any other app in App services.
+
+Application users can authenticate with either basic username/password
+credentials or OAuth client ID and client secret credentials. When
+authenticated, these users can access App services entities depending on
+their assigned permissions, their roles, and the permissions assigned to
+those roles.
+
+Using the username and password values specified when the application
+user was created, you can connect to the following URL (substituting the
+correct values for \<org-name\>,\<app-name\>, \<username\>, and
+\<password\>):
+
+    https://api.usergrid.com/management/<org-name>/<app-name>/token?grant_type=password&username=<username>&password=<password>
+
+The results show the access token needed to make subsequent API requests
+on behalf of the application user:
+
+    {
+      "access_token": "5wuGd-lcEeCUBwBQVsAACA:F8zeMOlcEeCUBwBQVsAACA:YXU6AAABMq0hdy4Lh0ewmmnOWOR-DaepCrpWx9oPmw",
+      "expires_in": 3600,
+      "user": {
+        "uuid": "e70b8677-e95c-11e0-9407-005056c00008",
+        "type": "user",
+        "username": "edanuff",
+        "email": "ed@anuff.com",
+        "activated": true,
+        "created": 1317164604367013,
+        "modified": 1317164604367013
+      }
+    }
+
+Using an access token
+---------------------
+
+When you obtain an access token, you must provide it with every
+subsequent API call that you make. There are two ways to provide your
+access token.
+
+-   You can add the token to the API querystring:\
+    \
+
+        https://api.usergrid.com/<org-name>/<app-name>/users?access_token=<access_token>
+
+-   You can include the token in an HTTP authorization header:\
+    \
+
+        Authorization: Bearer <access_token>
+
+**Note:** The App services documentation assumes you are providing a
+valid access token with every API call whether or not it is shown
+explicitly in the examples. Unless the documentation specifically says
+that you can access an API endpoint without an access token, you should
+assume that you must provide it.
+
+Safe mobile access
+------------------
+
+For mobile access, it is recommended that you connect as an application
+user with configured access control policies. Mobile applications are
+inherently untrusted because they can be easily examined and even
+decompiled.
+
+Any credentials stored in a mobile app should be considered secure only
+to the level of the application user. This means that if you don’t want
+the user to be able to access or delete data in your App services
+application, you need to make sure that you don’t enable that capability
+via roles or permissions. Because most web applications talk to the
+database using some elevated level of permissions, such as root, it’s
+generally a good idea for mobile applications to connect with a more
+restricted set of permissions. For more information, see [Managing
+access by defining permission
+rules](/managing-access-defining-permission-rules).



Mime
View raw message