You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2015/06/25 22:28:44 UTC
[46/51] [partial] incubator-usergrid git commit: Moving website from
SVN to Git.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/admin-user.md
----------------------------------------------------------------------
diff --git a/website/content/docs/admin-user.md b/website/content/docs/admin-user.md
new file mode 100644
index 0000000..24b9e14
--- /dev/null
+++ b/website/content/docs/admin-user.md
@@ -0,0 +1,781 @@
+---
+title: Admin user
+category: docs
+layout: docs
+---
+
+Admin user
+==========
+
+[See all management
+resources](/docs/usergrid/content/management-resources)[](/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 <ji...@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 <ji...@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 <ji...@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,
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/app-security.md
----------------------------------------------------------------------
diff --git a/website/content/docs/app-security.md b/website/content/docs/app-security.md
new file mode 100644
index 0000000..3c48ebe
--- /dev/null
+++ b/website/content/docs/app-security.md
@@ -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.
+
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/application.md
----------------------------------------------------------------------
diff --git a/website/content/docs/application.md b/website/content/docs/application.md
new file mode 100644
index 0000000..fe8cc77
--- /dev/null
+++ b/website/content/docs/application.md
@@ -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
+
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/applications.md
----------------------------------------------------------------------
diff --git a/website/content/docs/applications.md b/website/content/docs/applications.md
new file mode 100644
index 0000000..ebf7489
--- /dev/null
+++ b/website/content/docs/applications.md
@@ -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
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/assets.md
----------------------------------------------------------------------
diff --git a/website/content/docs/assets.md b/website/content/docs/assets.md
new file mode 100644
index 0000000..8e6b7c4
--- /dev/null
+++ b/website/content/docs/assets.md
@@ -0,0 +1,24 @@
+---
+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.
+
+
+ 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”)
+
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/authenticating-users-and-application-clients.md
----------------------------------------------------------------------
diff --git a/website/content/docs/authenticating-users-and-application-clients.md b/website/content/docs/authenticating-users-and-application-clients.md
new file mode 100644
index 0000000..2376347
--- /dev/null
+++ b/website/content/docs/authenticating-users-and-application-clients.md
@@ -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).
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/c8b7d6c5/website/content/docs/authentication-and-access-app-services-0.md
----------------------------------------------------------------------
diff --git a/website/content/docs/authentication-and-access-app-services-0.md b/website/content/docs/authentication-and-access-app-services-0.md
new file mode 100644
index 0000000..197dba6
--- /dev/null
+++ b/website/content/docs/authentication-and-access-app-services-0.md
@@ -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 <te...@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 <te...@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 <te...@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).