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/08/03 23:19:03 UTC
[7/9] incubator-usergrid git commit: Converted the security &
authentication section.
Converted the security & authentication section.
Project: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/commit/961a38f4
Tree: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/tree/961a38f4
Diff: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/diff/961a38f4
Branch: refs/heads/ug2-doc-update
Commit: 961a38f4465c38a6a6599bfc4356eeea6dd3a9d7
Parents: 445ac3e
Author: Dave Johnson <sn...@apache.org>
Authored: Mon Aug 3 14:07:38 2015 -0400
Committer: Dave Johnson <sn...@apache.org>
Committed: Mon Aug 3 14:07:38 2015 -0400
----------------------------------------------------------------------
docs/README.md | 25 ++-
docs/_static/css/theme.css | 4 +
docs/asset-and-files/tbd.md | 1 +
docs/counters-and-events/tbd.md | 1 +
docs/geolocation/tbd.md | 1 +
docs/index.rst | 31 ++--
docs/orgs-and-apps/tbd.md | 1 +
docs/push-notifications/tbd.md | 1 +
docs/sdks/tbd.md | 1 +
docs/security-and-auth/app-security.md | 19 +++
.../authenticating-api-requests.md | 38 +++++
...henticating-users-and-application-clients.md | 128 +++++++++++++++
.../changing-token-time-live-ttl.md | 61 +++++++
docs/security-and-auth/facebook-sign.md | 158 +++++++++++++++++++
.../security-and-auth/revoking-tokens-logout.md | 32 ++++
docs/security-and-auth/roles-and-permissions.md | 18 ---
docs/security-and-auth/securing-your-app.md | 44 ++++++
docs/security-and-auth/securitymodel0.png | Bin 0 -> 91321 bytes
.../user-authentication-types.md | 63 ++++++++
docs/security-and-auth/using-permissions.md | 115 ++++++++++++++
docs/src/main/resources/operation.mustache | 2 +-
docs/user-management/tbd.md | 1 +
22 files changed, 709 insertions(+), 36 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
index 6da14cf..204e90d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -43,6 +43,27 @@ A note about tables: simple tables are easy and you can find examples (e.g. conn
but for tables with multiple lines in each cell, you'll probably want to use a raw HTML table,
and there are plenty of examples of that around too.
-### The REST documentation
+### The REST API documentation
-TBD
+The REST API documentation in ``rest-endpoints/api-docs.md`` is generated from a Swagger file in the
+directory ``src/main/resources``, so DO NOT edit that file directly.
+
+If you need to update the REST API docs, you should edit the usergrid-swagger.yaml file and then
+ re-generate the file.
+
+If you need to change the formatting of the REST API docs, then you will need to edit the Mustache
+templates in ``src/main/resource`` and you may need to edit the Groovy script that does the
+generation: ``src/main/groovy/ApiDocGenerator``.
+
+You will need:
+* Groovy 2.x
+* [Mustache.java](https://github.com/spullara/mustache.java)
+
+Unfortunately, you will have to Git Clone Mustatche.java before you can run the generation script.
+
+This is the command to run the generation:
+
+ groovy src/main/groovy/ApiDocGenerator.groovy
+
+The script will update the file ``rest-endpoints/api-docs.md`` and when you are happy with your
+update you should commit and push that file with Git.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/_static/css/theme.css
----------------------------------------------------------------------
diff --git a/docs/_static/css/theme.css b/docs/_static/css/theme.css
index 17d12b3..870e633 100755
--- a/docs/_static/css/theme.css
+++ b/docs/_static/css/theme.css
@@ -5352,6 +5352,10 @@ h2.usergrid-DELETE-heading {
background-color: red;
}
+.rst-footer-buttons {
+ margin-bottom: 2em;
+}
+
/* css from petstore example */
body {
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/asset-and-files/tbd.md
----------------------------------------------------------------------
diff --git a/docs/asset-and-files/tbd.md b/docs/asset-and-files/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/asset-and-files/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/counters-and-events/tbd.md
----------------------------------------------------------------------
diff --git a/docs/counters-and-events/tbd.md b/docs/counters-and-events/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/counters-and-events/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/geolocation/tbd.md
----------------------------------------------------------------------
diff --git a/docs/geolocation/tbd.md b/docs/geolocation/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/geolocation/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index bcbca10..0bafb65 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -61,7 +61,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Push Notifications
- push-notifications/users-devices
+ push-notifications/tbd.md
.. _security-and-authentication:
@@ -69,7 +69,15 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Security and Authentication
- security-and-auth/roles-and-permissions
+ security-and-auth/app-security
+ security-and-auth/using-permissions
+ security-and-auth/authenticating-users-and-application-clients
+ security-and-auth/user-authentication-types
+ security-and-auth/changing-token-time-live-ttl
+ security-and-auth/authenticating-api-requests
+ security-and-auth/revoking-tokens-logout
+ security-and-auth/facebook-sign
+ security-and-auth/securing-your-app
.. _user-management-and-social-graph:
@@ -77,8 +85,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: User Management and Social Graph
- user-management/activity
- user-management/groups
+ user-management/tbd
.. _geolocation:
@@ -86,7 +93,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Geo-location
- geolocation/geolocation
+ geolocation/tbd
.. _asset-and-file-management:
@@ -94,8 +101,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Assets and Files
- asset-and-files/assets
- asset-and-files/file-storage-configuration
+ asset-and-files/tbd
.. _counters-and-events:
@@ -103,7 +109,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Counters and Events
- counters-and-events/events-and-counters
+ counters-and-events/tbd
.. _organization-and-application-management:
@@ -111,9 +117,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Organizations and Applications
- orgs-and-apps/applications
- orgs-and-apps/organizations-admins
-
+ orgs-and-apps/tbd
.. _rest-endpoints:
@@ -129,10 +133,7 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Client SDKs
- sdks/ios
- sdks/java
- sdks/javascript
- sdks/usage
+ sdks/tbd
.. _installation:
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/orgs-and-apps/tbd.md
----------------------------------------------------------------------
diff --git a/docs/orgs-and-apps/tbd.md b/docs/orgs-and-apps/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/orgs-and-apps/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/push-notifications/tbd.md
----------------------------------------------------------------------
diff --git a/docs/push-notifications/tbd.md b/docs/push-notifications/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/push-notifications/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/sdks/tbd.md
----------------------------------------------------------------------
diff --git a/docs/sdks/tbd.md b/docs/sdks/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/sdks/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/app-security.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/app-security.md b/docs/security-and-auth/app-security.md
new file mode 100644
index 0000000..9dcf3e2
--- /dev/null
+++ b/docs/security-and-auth/app-security.md
@@ -0,0 +1,19 @@
+# Security & token authentication
+
+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 API Services BaaS application.
+
+__Important__: When you register for the API Services BaaS, 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 [Using Permissions](managing-access-defining-permission-rules.html).
+2. Write code through which your app's users can verify who they are to your application. You do this by writing code that uses their username and password as credentials to initially authenticate with your application, then uses a token thereafter. (This authentication style supports the OAuth 2.0 model.) For more information, see [Authenticating users & app clients](autheticating-users-and-application-clients.html).
+3. Be sure to use coding best practices that help ensure that your app is protected from malicious attacks. For more information, see [Security best practices](security-best-practices.html).
+
+The following illustration describes these high-level areas.
+
+.. image:: securitymodel0.png
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/authenticating-api-requests.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/authenticating-api-requests.md b/docs/security-and-auth/authenticating-api-requests.md
new file mode 100644
index 0000000..c48bebd
--- /dev/null
+++ b/docs/security-and-auth/authenticating-api-requests.md
@@ -0,0 +1,38 @@
+# Authenticating API requests
+
+With the exception of the 'sandbox' application that is created with every API BaaS organization, all applications are secured by default. This means that to access your data store, a valid access token must be sent with all API requests to authenticate that the requester is authorized to make API calls to the resources they are attempting the access.
+
+This article describes how to use access tokens to access the API BaaS API, and how to manage access tokens, including revoking and changing token time to live.
+
+For information on generating access tokens/authenticating users and clients, see Authenticating users and application clients.
+
+## Authenticating with access tokens
+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://<usergrid-host>/{org-name}/{app-name}/users?access_token={access_token}
+
+You can include the token in an HTTP authorization header:
+
+ Authorization: Bearer {access_token}
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
+Note: The API BaaS 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.
+</p></div>
+
+## Authenticating with client ID and client secret
+
+Another option for authenticating your API requests is using either your organization client ID and client secret, or your application client ID and client secret, which will authenticate your request as an organization or application admin, respectively. Organization credentials can be found in the 'Org Overview' section of the admin portal, and application credentials can be found in the 'Getting Started' section of the admin portal.
+
+<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">
+Warning: For server-side use only
+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 Security best practices for additional considerations in keeping access to your app and its data secure.
+</p></div>
+
+This can be a convenient way to authenticate API requests, since there is no need to generate and manage an access token, but please note that you should be very cautious when implementing this type of authentication. Organization-level authentication grants full permission to perform any supported call against your organization and every application in it, and application-level authentication grants full permission to perform any supported call against all of the resources in an application. Should your client id and client secret be compromised, a malicious user would gain broad access to your organization or application.
+
+To authenticate using client id and secret, append the following parameters to your request URL:
+
+ client_id=<your-client-id>&client_secret=<your-client-secret>
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/authenticating-users-and-application-clients.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/authenticating-users-and-application-clients.md b/docs/security-and-auth/authenticating-users-and-application-clients.md
new file mode 100644
index 0000000..54dded0
--- /dev/null
+++ b/docs/security-and-auth/authenticating-users-and-application-clients.md
@@ -0,0 +1,128 @@
+# Authenticating users & app clients
+
+To protect your App Services 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.
+
+<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">
+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 [Using Permissions](using-permissions.html).
+</p></div>
+
+
+## Authentication levels
+App Services supports four levels of authentication:
+
+* __Application user__: Grant's user access to an API Services application, based on the roles and permissions assigned to the user.
+* __Application client__: Grants full access to perform API requests against an API Services application.
+* __Organization client__: Grants full access to perform API requests against an API Services organization.
+* __Admin user__: Grants full access to perform API requests against any API Services organization that the user is an admin of.
+
+Because the scope of access provided by the application client, organization client, and admin user authentication levels is so broad (and as a result, so powerful), it's a bad practice to use them from a mobile app or any client-side code. Instead, they're better suited to server-side implementations, such as web applications.
+
+For a more detailed description of available authentication levels, see [Authentication levels](user-authentication-types.html).
+
+## Application user authentication (user login)
+Using the username and password values specified when the user entity was created, your app can connect to the App Services application endpoint to request an access token. It's also acceptable to use the user's email address in place of the username.
+
+### Using the SDKs
+When a user is logged in using the Apigee iOS, JavaScript, node.JS and Android SDKs, the returned token is automatically stored in the ApigeeDataClient (iOS), DataClient (Android), or Apigee.Client (JavaScript/node.JS) class instance, and will be sent to the API with all subsequent method calls.
+
+#### Request syntax
+
+ curl -X POST "https://api.usergrid.com/<orgName>/<appName>/token" -d '{"grant_type":"password", "username":<username>, "password":<password>}'
+
+#### Example request
+
+ curl -X POST "https://api.usergrid.com/my-org/my-app/token" -d '{"grant_type":"password", "username":"john.doe", "password":"testpw"}'
+
+#### Example response
+
+The results include the access token needed to make subsequent API requests on behalf of the application user:
+
+ {
+ "access_token": "5wuGd-lcEeCUBwBQVsAACA:F8zeMOlcEeCUBwBQVsAACA:YXU6AAABMq0hdy4",
+ "expires_in": 3600,
+ "user": {
+ ...
+ }
+ }
+
+## Application client authentication
+Using your app’s client id and client secret values, your app can connect to the App Services application endpoint to request an access token. The client ID and secret for your app can be found in 'Getting Started' section of the API Services admin portal, under 'Server App Credentials'.
+
+<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">
+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" in [Authenticating API requests](authenticating-api-requests.html) for additional considerations in keeping access to your app and its data secure.
+</p></div>
+
+### Request syntax
+
+ curl -X POST "https://api.usergrid.com/<orgName>/<appName>/token" -d '{"grant_type":"client_credentials", "client_id":<application_clientID>, "client_secret":"<application_client_secret>"}'
+
+### Example request
+
+ curl -X POST "https://api.usergrid.com/my-org/my-app/token" -d '{"grant_type":"client_credentials", "client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ", "client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'
+
+### Example response
+
+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": {
+ ...
+ }
+ }
+
+## Admin user authentication
+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.
+
+<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">
+Warning: Authenticating as an admin user grants full access to one or more organizations and all of the applications contained in those organizations. Due to this, be cautious when implementing this type of authentication in client-side code. Instead, consider implementing admin user access in server-side code only. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html) for additional considerations in keeping access to your app and its data secure.
+</p></div>
+
+### Request syntax
+
+ curl -X POST "https://api.usergrid.com/management/token" -d '{"grant_type":"password", "username":<admin_username>, "password":<admin_password>}'
+
+### Example Request
+
+ curl -X POST "https://api.usergrid.com/management/token" -d '{"grant_type":"password", "username":"testadmin", "password":"testadminpw"}'
+
+### Example response
+
+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": {
+ ...
+ }
+ }
+
+## Organization client authentication
+If you do require organization level access, your app can connect to the App Services management endpoint to request an access token. Access to an organization requires the client id and client secret credentials. The client ID and secret for your organization can be found on the 'Org Administration' page of the API Services admin console under 'Organization API Credentials'.
+
+<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">
+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" in [Authenticating API requests](authenticating-api-requests.html for additional considerations in keeping access to your app and its data secure.
+</p></div>
+
+### Request syntax
+
+ curl -X POST "https://api.usergrid.com/management/token" -d '{"grant_type":"client_credentials", "client_id":<org_clientID>, "client_secret":<org_client_secret>}'
+
+### Example request
+
+ curl -X POST "https://api.usergrid.com/management/token" -d '{"grant_type":"client_credentials", "client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ", "client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'
+
+### Example response
+
+The results include the access token needed to make subsequent API requests to the organization:
+
+ {
+ "access_token": "gAuFEOlXEeCfRgBQVsAACA:b3U6AAABMqz-Cn0wtDxxkxmQLgZvTMubcP20FulCZQ",
+ "expires_in": 3600,
+ "organization": {
+ ...
+ }
+ }
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/changing-token-time-live-ttl.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/changing-token-time-live-ttl.md b/docs/security-and-auth/changing-token-time-live-ttl.md
new file mode 100644
index 0000000..1dcdd4e
--- /dev/null
+++ b/docs/security-and-auth/changing-token-time-live-ttl.md
@@ -0,0 +1,61 @@
+# Changing token expiration (time-to-live)
+
+An access token has a “time-to-live” (ttl), which is the maximum time that the access token will be valid for use within the application. With the API Baas, you can change the default ttl for all application user tokens, set the ttl for an individual token at the time of creation, or revoke one or more tokens. This gives you a high degree of control over access to your API Baas account and data store.
+
+## Default ttl
+By default, all tokens have a system-defined time-to-live of 7 days (604800 seconds). Note that Token ttl is specified in milliseconds, but when a token is created, the API response will return the ttl in seconds.
+
+## Changing the default ttl
+You can change the default ttl for all application user tokens (that is, tokens associated with a user entity) by updating the application entity’s accesstokenttl property. Changing the default ttl will only affect new tokens. Any existing tokens will not be affected.
+
+Please note that this does not apply to application client, organization client or admin user tokens. For more on obtaining tokens for these other authorization levels, see [Authenticating users and application clients](authenticating-users-and-application-clients.html).
+
+__Note__: If you set ttl=0, the token will never expire. This can pose a security risk and should be used with caution.
+
+### Request syntax
+
+ curl -X PUT https://api.usergrid.com/<org_name>/<app_name> -d '{"accesstokenttl":<ttl_in_milliseconds>}'
+
+### Example Request
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app -d '{"accesstokenttl":"1800000"}'
+
+### Example response
+
+ {
+ "action" : "put",
+ "application" : "d878de4r-99a7-11e3-b31d-5373d7165c2d",
+ "params" : {
+ "access_token" : [ "DFR4d5M1mJmoEeOGVPncm-g9qgAAAURv_lfQ7uu6aYHjJJn7QCrGoVnvU-ob5Ko" ]
+ },
+ "uri" : "https://api.usergrid.com/amuramoto/secured",
+ "entities" : [ {
+ "uuid" : "d878de4r-99a7-11e3-b31d-5373d7165c2d",
+ "type" : "application",
+ "name" : "your-org/your-app",
+ "created" : 1392843003032,
+ "modified" : 1392843615777,
+ "accesstokenttl" : 1800000,
+ "organizationName" : "your-org",
+ "applicationName" : "your-app",
+ "apigeeMobileConfig" : "{...}",
+ "metadata" : {
+ "collections" : [ "activities", "assets", "devices", "events", "folders", "groups", "roles", "users" ]
+ }
+ } ],
+ "timestamp" : 1392843615767,
+ "duration" : 28,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+## Changing ttl when a token is created
+When you request an access token, you can override its ttl by including a ttl property in the body of the request when the token is created. This applies to tokens for all authentication levels, including application user, admin user, organization client, and application client authentication levels.
+
+The ttl must be equal to or less than the value of the application entity's 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.
+
+For example, the following would create an application user token with a ttl of 180000000 milliseconds:
+
+ curl -X POST https://api.usergrid.com/your-org/your-app/token -d '{"username":"someUser", "password":"somePassword", "grant_type":"password", "ttl":"180000000"}'
+
+__Note__: If you set ttl=0, the token will never expire. This can pose a security risk and should be used with caution.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/facebook-sign.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/facebook-sign.md b/docs/security-and-auth/facebook-sign.md
new file mode 100644
index 0000000..55be0de
--- /dev/null
+++ b/docs/security-and-auth/facebook-sign.md
@@ -0,0 +1,158 @@
+# Facebook sign in
+
+You can authenticate your App Services requests by logging into Facebook. To access App Services resources, you need to provide an access token with each request (unless you use the sandbox app). You can get an access token by connecting to an appropriate web service endpoint and providing the correct client credentials — this is further described in Authenticating users and application clients. However, you can also obtain an access token by logging into Facebook.
+
+To enable authentication to App Services through Facebook, do the following in your app:
+
+1. Make a login call to the Facebook API (do this using the Facebook SDK or API). If the login succeeds, a Facebook access token is returned.
+2. Send the Facebook access token to App Services. If the Facebook access token is valid and the user does not already exist in App Services, App Services provisions a new App Services user. It also returns an App Services access token, which you can use for subsequent App Services API calls. Behind the scenes, App Services uses the Facebook access token to retrieve the user's profile information from Facebook.
+3. If the Facebook access token is invalid, Facebook returns an OAuth authentication error, and the login does not succeed.
+
+The request to authenticate to App Services using a Facebook access token is:
+
+ GET https://api.usergrid.com/{my_org}/{my_app}/auth/facebook?fb_access_token={fb_access_token}
+
+where:
+
+* ``{my_org}`` is the organization UUID or organization name.
+* ``{my_app}`` is the application UUID or application name.
+* ``{fb_access_token}`` is the Facebook access token.
+
+## Facebook login example
+The Facebook technical guides for login present detailed information on how to add Facebook login to your app. Instructions are provided for JavaScript, iOS, and Android.
+
+In brief, here are the steps for JavaScript. You can see these steps implemented in the Facebook login example packaged with the JavaScript SDK for App Services (which you can download in ZIP format or tar.gz format). The Facebook login example is in the /examples/facebook directory of the extracted download. The code example snippets shown below are taken from the Facebook login example.
+
+### Step 1: Create a Facebook app
+Create a new app on the Facebook App Dashboard. Enter your app's basic information. Once created, note the app ID shown at the top of the dashboard page.
+
+### Step 2: Invoke the Facebook OAuth dialog
+Invoke the Facebook OAuth Dialog. To do that, redirect the user's browser to a URL by inserting the following Javascript code after the opening <body> tag in your app’s HTML file:
+
+ https://www.facebook.com/dialog/oauth/?
+ client_id={YOUR_APP_ID}
+ &redirect_uri={YOUR_REDIRECT_URL}
+ &state={YOUR_STATE_VALUE}
+ &scope={COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES}
+ &response_type={YOUR_RESPONSE_TYPE}
+
+where:
+
+``{YOUR_APP_ID}`` is the app ID.
+``{YOUR_REDIRECT_URL}`` is the application UUID or application name.
+``{YOUR_STATE_VALUE}`` is a unique string used to maintain application state between the request and callback.
+``{COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES}`` is a comma separated list of permission names which you would like the user to grant your application.
+``{YOUR_RESPONSE_TYPE}``is the requested response type, either code or token. Defaults to code. Set the response type to token. With the response type set to token, the Dialog's response will include an OAuth user access token in the fragment of the URL the user is redirected to, as per the client-side authentication flow.
+
+Here is how it’s done in the Facebook login example:
+
+ var apiKey = $("#api-key").val();
+ var location = window.location.protocol + '//' + window.location.host;
+ var path = window.location.pathname;
+
+ var link = "https://www.facebook.com/dialog/oauth?client_id=";
+ link += apiKey;
+ link += "&redirect_uri=";
+ link += location+path
+ link += "&scope&COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES&response_type=token";
+
+ //now forward the user to facebook
+ window.location = link;
+
+Notice that the response type is set to token. As a result, a Facebook access token will be appended to the URL to which the user is redirected.
+
+### Step 3: Add the JavaScript SDK for Facebook
+Add the following Javascript SDK initialization code after the code that invokes the Facebook OAuth Dialog. The code will load and initialize the JavaScript SDK in your HTML page. Replace ``YOUR_APP_ID`` with the App ID noted in Step 1, and WWW.YOUR_DOMAIN.COM with your own domain.
+
+ window.fbAsyncInit = function() {
+ FB.init({
+ appId : 'YOUR_APP_ID', // App ID
+ channelUrl : '//WWW.YOUR_DOMAIN.COM/channel.html', // Channel File
+ status : true, // check login status
+ cookie : true, // enable cookies to allow the server to access the session
+ xfbml : true // parse XFBML
+ });
+
+Here is how the window.fbAsynchInit() function is implemented in the Facebook login example:
+
+ //load up the facebook api sdk
+ window.fbAsyncInit = function() {
+ FB.init({
+ appId : '308790195893570', // App ID
+ channelUrl : '//usergridsdk.dev//examples/channel.html', // Channel File
+ status : true, // check login status
+ cookie : true, // enable cookies to allow the server to access the session
+ xfbml : true // parse XFBML
+ });
+ };
+
+### Step 4. Setup FB.login
+Whenever a user is either not logged into Facebook or not authorized for an app, it is useful to prompt them with the relevant dialog. The ``FB.login()`` Javascript SDK function automatically displays the correct one to the user.
+
+To integrate ``FB.login()`` function in your existing code:
+
+ function login() {
+ FB.login(function(response) {
+ if (response.authResponse) {
+ // connected
+ } else {
+ // cancelled
+ }
+ });
+ }
+
+Here is how ``FB.login()`` is implemented in the Facebook login example:
+
+ function login(facebookAccessToken) {
+ client.loginFacebook(facebookAccessToken, function(err, response){
+ var output = JSON.stringify(response, null, 2);
+ if (err) {
+ var html = '<pre>Oops! There was an error logging you in. \r\n\r\n';
+ html += 'Error: \r\n' + output+'</pre>';
+ } else {
+ var html = '<pre>Hurray! You have been logged in. \r\n\r\n';
+ html += 'Facebook Token: ' + '\r\n' + facebookAccessToken + '\r\n\r\n';
+ html += 'Facebook Profile data stored in Usergrid: \r\n' + output+'</pre>';
+ }
+ $('#facebook-status').html(html);
+ })
+ }
+
+The ``client.loginFacebook()`` function is provided by the App Services JavaScript SDK. It uses the Facebook auth token to obtain an App Services auth token. If the Facebook access token is valid and the user does not already exist in App Services, the function creates a user entity for the user. It also uses the Facebook access token to retrieve the user's profile information from Facebook.
+
+Here is what the ``client.loginFacebook()`` function looks like:
+
+ Apigee.Client.prototype.loginFacebook = function (facebookToken, callback) {
+ var self = this;
+ var options = {
+ method:'GET',
+ endpoint:'auth/facebook',
+ qs:{
+ fb_access_token: facebookToken
+ }
+ };
+ this.request(options, function(err, data) {
+ var user = {};
+ if (err && self.logging) {
+ console.log('error trying to log user in');
+ } else {
+ user = new Apigee.Entity('users', data.user);
+ self.setToken(data.access_token);
+ }
+ if (typeof(callback) === 'function') {
+ callback(err, data, user);
+ }
+ });
+ }
+
+Notice that the function also returns an App Services access token, which you can use for subsequent App Services API calls.
+
+Remember to create a client for your app, which is the main entry point to the JavaScript SDK for App Services. You need to do this before you can use the SDK. Here’s the code to create a client:
+
+ var client = new Apigee.Client({
+ orgName:'yourorgname',
+ appName:'yourappname',
+ logging: true, //optional - turn on logging, off by default
+ buildCurl: true //optional - turn on curl commands, off by default
+ });
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/revoking-tokens-logout.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/revoking-tokens-logout.md b/docs/security-and-auth/revoking-tokens-logout.md
new file mode 100644
index 0000000..ffbadcb
--- /dev/null
+++ b/docs/security-and-auth/revoking-tokens-logout.md
@@ -0,0 +1,32 @@
+# Revoking tokens (logout)
+
+Under certain circumstances, you may need to explicitly revoke one or more tokens associated with a user entity, such as when a user logs out of your app. This is accomplished by making a PUT request to the /revoketoken and /revoketokens endpoints.
+
+## Revoking tokens (user logout)
+If a user has been logged in using the Apigee iOS, Android, JavaScript or node.JS SDKs, the returned token is automatically stored in the ApigeeDataClient (iOS), DataClient (Android), Apigee.Client (JavaScript), Usergrid.Client (node.JS) class instance. Calling the logout method of the SDK will destroy the token on the server, as well as in the client object.
+
+### Request syntax
+
+Revoke all tokens associated with a user entity
+
+ curl -X PUT https://api.usergrid.com/<org_name>/<app_name>/users/<user_uuid_or_username>/revoketokens
+
+Revoke a specific token associated with a user entity
+
+ curl -X PUT https://api.usergrid.com/<org_name>/<app_name>/users/<user_uuid_or_username>/revoketoken?token=<token_to_revoke>
+
+### Example request
+
+ curl -X PUT https://api.usergrid.com/your-org/your-app/users/someUser/revoketokens
+
+Example response
+
+ {
+ "action" : "revoked user token",
+ "timestamp" : 1382050891455,
+ "duration" : 24
+ }
+
+### Revoking admin user tokens
+
+The /revoketoken and /revoketokens endpoints also work for revoking admin user tokens by making a PUT request to /management/users/<org_admin_username>/
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/roles-and-permissions.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/roles-and-permissions.md b/docs/security-and-auth/roles-and-permissions.md
deleted file mode 100644
index d237c13..0000000
--- a/docs/security-and-auth/roles-and-permissions.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Roles & Permissions
-
-## Roles
-
-A role represents a set of permissions that enable certain operations to
-be performed on a specific endpoint. You can assign a user to a role,
-and in this way give the user the permissions associated with that role.
-
-**Note:** The /rolenames endpoint is no longer valid. If your code currently
-makes calls to /rolenames, you need to change the calls to use /roles.
-
-## Permissions
-
-Each role contains multiple permissions. Permissions work by whitelisting by default, meaning any permission that is not explicitely granted is denied by default. Permission is an HTTP verb (GET to allow reads, POST to allow creation, PUT to allow edits and DELETE to allow deletes) combined with a path, with optional wildcards. For example the permission put:/users/* allows editing any user.
-
-Permissions can be added to roles, groups or to users directly, and a user’s permission is the combination of its personal permissions and the permissions of any role he’s been assigned, and the permissions of any group he’s a member of.
-
-Permissions are only valid within the scope of a single application, so the permission paths do not need to be prefixed with /org\_name\_or\_uuid/app\_name\_or\_uuid.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/securing-your-app.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/securing-your-app.md b/docs/security-and-auth/securing-your-app.md
new file mode 100644
index 0000000..7030aef
--- /dev/null
+++ b/docs/security-and-auth/securing-your-app.md
@@ -0,0 +1,44 @@
+# Security best practices
+
+There a number of actions you should take to ensure that your app is secure before you put it into production. The following is not an exhaustive list, but offers some common best practices you should consider following to keep your app secure when using the API BaaS.
+
+## Never use the 'sandbox' for a production app
+By default, every new API BaaS account has an app named “sandbox” that is already created under your new organization. This app is no different than any other app that you might create, except that the Guest role has been given full permissions (that is, /** for GET, POST, PUT, and DELETE). This eliminates the need for a token when making application level calls, and can make it much easier to get your app up and running; however, it also means that any data in the sandbox application is completely unsecured.
+
+As with any other app, you can secure the sandbox application by updating its roles and permissions. For more on working with permissions and roles, see [Using Permissions](using-permissions.html).
+
+## Review permissions in your apps
+Prior to launching your app into a production environment, it is advisable to review all the roles and permissions you have set up, as well as the groups and users you have assigned those permissions and roles to. During development, you may find that you added various permissions which may or may not still be required once the app is complete. Review all permissions and delete any that are no longer required.
+
+Prior to taking your app live, you should secure it by removing any unnecesary Guest permissions. (See [Using Permissions](using-permissions.html) for further information about setting permissions.) After you secure your the app, any calls to the API will need to include an OAuth token. Oauth tokens (also called access tokens) are obtained by the API in response to successful authentication calls. Your app saves the token and uses it for all future calls during that session. Learn more about access tokens in Authenticating users and application clients.
+
+## Edit the 'default' role
+When preparing an application for production use, a good first step is to edit permission rules for the Default role. The permissions in this role will be applied to every user who authenticates with a valid access token.
+
+For example, in the Default role, you will most likely first want to remove the permission rule that grants full access to all authenticated users:
+
+ GET,PUT,POST,DELETE:/users/me/**
+
+For more on roles, see [Using Permissions](using-permissions.html).
+
+Review test accounts
+If you created any test user or test administrator accounts during development, these should also be reviewed for relevancy and security. Delete any test accounts that are no longer needed. If these accounts are still needed, make sure that passwords have been secured to the standards required by your app.
+
+## Use https
+Make sure that any calls you make to the API are done using the secure https protocol, and not the insecure http protocol.
+
+If your app is a web app, that is, an app served by a web server, make sure that the app is served using https.
+
+## Acquire access tokens in a secure way
+There are various methods for acquiring an access token (see [Authenticating users and application clients](authenticating-users-and-application-clients.html). One method is to use the application or organization level client secret-client id combination. This method should not be used in client applications (this is, apps that are deployed to a device, and which authenticate and make calls against the API).
+
+That’s because a hacker could analyze your app (even a compiled, binary distribution of your app), and retrieve the secret-id combination. Armed with this information, an attacker could gain full access to the data in your account.
+
+Instead, use application user credentials. This means that your app’s users should provide a username and password. Your app would use these to authenticate against the API and retrieve an access token.
+
+The client secret-client id combination should be used only in secure, server-side applications where there is no possibility of a hacker gaining control of the credentials.
+
+## Treat mobile clients as untrustworthy
+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 API BaaS 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 [Using Permissions](using-permissions.html).
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/securitymodel0.png
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/securitymodel0.png b/docs/security-and-auth/securitymodel0.png
new file mode 100644
index 0000000..9f3ee82
Binary files /dev/null and b/docs/security-and-auth/securitymodel0.png differ
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/user-authentication-types.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/user-authentication-types.md b/docs/security-and-auth/user-authentication-types.md
new file mode 100644
index 0000000..79e140f
--- /dev/null
+++ b/docs/security-and-auth/user-authentication-types.md
@@ -0,0 +1,63 @@
+# Authentication levels
+
+App Services 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 application or web clients that require higher-level access to your App Services application or organization. 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.
+
+## Configuring authentication levels
+Access permissions can only be configured for the 'application user' – this can be done both programmatically and in the admin portal. The application, organization and admin clients cannot be configured, and can only be accessed programmatically via the API.
+
+For more about creating and managing roles and permissions for application users, see Managing access by defining permission rules. For a look at how security features fit together, see App Security Overview.
+
+## User authentication level
+
+<table class="usergrid-table">
+<tr>
+ <th>Authentication Level</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td>Application user</td>
+ <td>This is the standard authentication type you will use to implement user login for your app. The application user level allows access to your App Services application as governed by the permission rules you create and associated with users and user groups. For more on setting permissions see Managing access by defining permission rules. Each Application User is represented by a User entity in your App Services application. For more about the User entity, see User.</td>
+</tr>
+</table>
+
+## Admin authentication levels
+
+<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">
+Warning: Safe use of admin authentication levels. Never use client ID and client secret, or any hard-coded credentials to 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. Even when authenticating with username and password, be cautious when using these authentication levels since they grant broad access to your App Services account. See "safe mobile access" in Authenticating API requests for additional considerations in keeping access to your app and its data secure.</p></div>
+
+<table class="usergrid-table">
+<tr>
+ <th>Authentication Level</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td>Application client</td>
+ <td>Grants full access to perform any operation on an App Services application (but not other applications within the same organization).
+
+ <p>Authentication at this level is useful in a server-side application (not a mobile app) that needs access to resources through the App Services API. For example, imagine you created a website that lists every hiking trail in the Rocky Mountains. You would want anyone to be able to view the content, but would not want them to access the App Services API and all your data directly. Instead, you would authenticate as an application client in your server-side code to access the data via the API in order to serve it to your website's visitors.</p></td>
+</tr>
+<tr>
+ <td>Organization client</td>
+ <td>Grants full access to perform any operation on an App Services organization.
+
+ <p>This authentication level provides the greatest amount of access to an individual organization, allowing a client to perform any operation on an App Services organization and any applications in that organization. This level of access should be used sparingly and carefully.</p></td>
+</tr>
+<tr>
+ <td>Admin user</td>
+ <td>Allows full access to perform any operation on all organization accounts of which the admin user is a member.
+
+ <p>This authentication level is useful from applications that provide organization-wide administration features. For example, the App Services admin portal uses this level of access because it requires full access to the administration features.</p>
+
+ 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.</td>
+</tr>
+</table>
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/security-and-auth/using-permissions.md
----------------------------------------------------------------------
diff --git a/docs/security-and-auth/using-permissions.md b/docs/security-and-auth/using-permissions.md
new file mode 100644
index 0000000..092d987
--- /dev/null
+++ b/docs/security-and-auth/using-permissions.md
@@ -0,0 +1,115 @@
+# Using permissions
+
+Permissions allow you to define user access to perform GET, POST, PUT, or DELETE operations on specific resources. When the user submits a request via your app code to the API BaaS API, the user’s permissions are checked against the resource paths that the user is trying to access. The request succeeds only if access to the resource is allowed by the permission rules you specify.
+
+## Permissions syntax
+In API BaaS, permissions are represented in the following format:
+
+ <operations>:<resource_path>
+
+* ``<operations>``: A comma-delimited set of HTTP methods (``GET``, ``PUT``, ``POST``, ``DELETE``) that are allowed for the specified resource path. For example, ``get``, ``post`` would allow only ``GET`` and ``POST`` requests to be made to the specified resource.
+* ``<resource_path>``: The path to the resources to be accessed. For example, ``/users`` would apply the permission to the users collection, while ``/users/Tom`` would apply the permission to only the user entity with username 'Tom'.
+
+## Complex paths
+Complex paths can be defined using [Apache Ant pattern syntax](http://ant.apache.org/manual/dirtasks.html#patterns). The following special path variables are supported for the construction of complex paths:
+
+<table>
+<tr>
+ <td>Parameter</td>
+ <td>Description</td>
+</tr>
+<tr>
+ <td>*</td>
+ <td>Treated as a wildcard. Assigns the permission to all paths at the specified level in the path hierarchy. For example, ``/*`` would match any collection, while ``/users/Tom/*`` would match /users/Tom/likes and ``/users/Tom/owns``.</td>
+</tr>
+<tr>
+ <td>**</td>
+ <td>Assigns the permission to the path recursively. For example, ``**/likes`` would match ``/likes`` and ``/users/likes``, while ``/users/**`` would match ``/users`` and ``/users/likes``.</td>
+</tr>
+<tr>
+ <td>\${user}</td>
+ <td>Automatically sets the path segment to the UUID of the currently authenticated user. For example, if you sent a request with a valid access token for a user with UUID ``bd397ea1-a71c-3249-8a4c-62fd53c78ce7``, the path ``/users/${user}`` would be interpreted as ``/users/bd397ea1-a71c-3249-8a4c-62fd53c78ce7``, assigning the permission only to that user entity.</td>
+</tr>
+</table>
+
+## Assigning permissions
+Permissions can only be assigned to user, group or role entities. Assigning permissions to roles can be particularly useful, as it allows you to create sets of permissions that represent complex access definitions, which can then be assigned to user and group entities. For more on roles, see Using roles.
+
+### Request syntax
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions -d '{"permission":<permissions>}'
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection The collection of the entity that the permissions are to be assigned to.
+entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
+permissions The permissions to assign to the entity. See Permissions syntax for format.
+
+For collections, Valid values are users and groups.
+
+### Example request
+For example, the following cURL request would give the user 'Tom' POST permission to the /users collection:
+
+ curl -X POST https://api.usergrid.com/your-org/your-app/users/Tom/permissions -d '{"permission":"post:/users"}'
+
+### Example response
+The newly assigned permission is returned in the data property of the response:
+
+ {
+ "action" : "post",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "uri" : "https://api.usergrid.com/your-org/your-app",
+ "entities" : [ ],
+ "data" : [ "post:/users" ],
+ "timestamp" : 1402349612382,
+ "duration" : 19,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+
+## Removing permissions
+Using a DELETE request, you can remove one of more permissions from a user, group, or role entity.
+
+### Request syntax
+
+ curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions?=<permissions>
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+collection The collection of the entity that the permissions are to be assigned to. Valid values are users and groups.
+entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
+permissions The permissions to assign to the entity. See [Permissions syntax](using-permissions.html) for format.
+
+
+### Example request
+
+ curl -X DELETE https://api.usergrid.com/your-org/your-app/users/Tom/permissions?permission=post:/users
+
+### Example response
+The deleted permission is returned in the params.permission property of the response:
+
+ {
+ "action" : "delete",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "permission" : [ "post:/users" ]
+ },
+ "uri" : "https://api.usergrid.com/your-org/your-app",
+ "entities" : [ ],
+ "data" : [ "post:/assets" ],
+ "timestamp" : 1402349951530,
+ "duration" : 20,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/src/main/resources/operation.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/operation.mustache b/docs/src/main/resources/operation.mustache
index d19ec70..cce0524 100644
--- a/docs/src/main/resources/operation.mustache
+++ b/docs/src/main/resources/operation.mustache
@@ -6,7 +6,7 @@
<h3>Parameters</h3>
{{#parameters}}
-* __{{name}}__ ({{#type}}({{type}}){{/type}}{{#schemaRef}}[{{schemaRef}}](#{{schemaAnchor}}){{/schemaRef}})
+* __{{name}}__ ({{#type}}{{type}}{{/type}}{{#schemaRef}}[{{schemaRef}}](#{{schemaAnchor}}){{/schemaRef}})
{{description}} (Specified in {{in}}).
{{/parameters}}
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/961a38f4/docs/user-management/tbd.md
----------------------------------------------------------------------
diff --git a/docs/user-management/tbd.md b/docs/user-management/tbd.md
new file mode 100644
index 0000000..f65681d
--- /dev/null
+++ b/docs/user-management/tbd.md
@@ -0,0 +1 @@
+# Coming soon...
\ No newline at end of file