From b5ca8ba5bcd2ba5f61665d71ded70d52cf170e02 Mon Sep 17 00:00:00 2001
From: vishalnayak <vishalnayakv@gmail.com>
Date: Sat, 5 Mar 2016 00:54:48 -0500
Subject: [PATCH] Documentation for capabilities and capabilities-self APIs

---
 command/capabilities.go                       | 15 ++++--
 .../docs/http/sys-capabilities-self.html.md   | 44 +++++++++++++++++
 .../source/docs/http/sys-capabilities.html.md | 48 +++++++++++++++++++
 website/source/layouts/http.erb               |  8 ++++
 4 files changed, 110 insertions(+), 5 deletions(-)
 create mode 100644 website/source/docs/http/sys-capabilities-self.html.md
 create mode 100644 website/source/docs/http/sys-capabilities.html.md

diff --git a/command/capabilities.go b/command/capabilities.go
index 0c637c37b6..17e8b59712 100644
--- a/command/capabilities.go
+++ b/command/capabilities.go
@@ -33,6 +33,10 @@ func (c *CapabilitiesCommand) Run(args []string) int {
 	case len(args) == 2:
 		token = args[0]
 		path = args[1]
+	default:
+		flags.Usage()
+		c.Ui.Error(fmt.Sprintf("\ncapabilities expects at least one argument"))
+		return 1
 	}
 
 	client, err := c.Client()
@@ -67,12 +71,13 @@ func (c *CapabilitiesCommand) Help() string {
 Usage: vault capabilities [options] [token] path
 
   Fetch the capabilities of a token on a given path.
-  If a token is provided to the command, API '/sys/capabilities' will be invoked
-  with the given token; otherwise API '/sys/capabilities-self' will be invoked with
-  the client token.
+  If a token is provided as an argument, '/sys/capabilities' endpoint will be invoked
+  with the given token; otherwise '/sys/capabilities-self' endpoing will be invoked
+  with the client token.
 
-  Note that this command will respond with a ["deny"] capability if the given path
-  is invalid.
+  If a token does not have any capability on a given path, or if any of the policies
+  belonging to the token explicitly had ["deny"] capability, or if the argument path
+  is invalid, this command will respond with a ["deny"].
 
 General Options:
 
diff --git a/website/source/docs/http/sys-capabilities-self.html.md b/website/source/docs/http/sys-capabilities-self.html.md
new file mode 100644
index 0000000000..df51ecfb97
--- /dev/null
+++ b/website/source/docs/http/sys-capabilities-self.html.md
@@ -0,0 +1,44 @@
+---
+layout: "http"
+page_title: "HTTP API: /sys/capabilities-self"
+sidebar_current: "docs-http-auth-capabilities-self"
+description: |-
+  The `/sys/capabilities-self` endpoint is used to fetch the capabilities of client token on a given path.
+---
+
+# /sys/capabilities-self
+
+## POST
+
+<dl>
+  <dt>Description</dt>
+  <dd>
+    Returns the capabilities of client token on the given path.
+    Client token is the Vault token with which this API call is made.
+  </dd>
+
+  <dt>Method</dt>
+  <dd>POST</dd>
+
+  <dt>Parameters</dt>
+  <dd>
+    <ul>
+      <li>
+        <span class="param">path</span>
+        <span class="param-flags">required</span>
+	Path on which the client token's capabilities will be checked.
+      </li>
+    </ul>
+  </dd>
+
+  <dt>Returns</dt>
+  <dd>
+
+    ```javascript
+	{
+		"capabilities": ["read", "list"]
+	}
+    ```
+
+  </dd>
+</dl>
diff --git a/website/source/docs/http/sys-capabilities.html.md b/website/source/docs/http/sys-capabilities.html.md
new file mode 100644
index 0000000000..fc2e7c5e63
--- /dev/null
+++ b/website/source/docs/http/sys-capabilities.html.md
@@ -0,0 +1,48 @@
+---
+layout: "http"
+page_title: "HTTP API: /sys/capabilities"
+sidebar_current: "docs-http-auth-capabilities"
+description: |-
+  The `/sys/capabilities` endpoint is used to fetch the capabilities of a token on a given path.
+---
+
+# /sys/capabilities
+
+## POST
+
+<dl>
+  <dt>Description</dt>
+  <dd>
+    Returns the capabilities of the token on the given path.
+  </dd>
+
+  <dt>Method</dt>
+  <dd>POST</dd>
+
+  <dt>Parameters</dt>
+  <dd>
+    <ul>
+      <li>
+        <span class="param">token</span>
+        <span class="param-flags">required</span>
+	Token for which capabilities are being queried.
+      </li>
+      <li>
+        <span class="param">path</span>
+        <span class="param-flags">required</span>
+	Path on which the token's capabilities will be checked.
+      </li>
+    </ul>
+  </dd>
+
+  <dt>Returns</dt>
+  <dd>
+
+    ```javascript
+	{
+		"capabilities": ["read", "list"]
+	}
+    ```
+
+  </dd>
+</dl>
diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb
index ee75b37f9c..b8ea3443e1 100644
--- a/website/source/layouts/http.erb
+++ b/website/source/layouts/http.erb
@@ -69,6 +69,14 @@
 						<li<%= sidebar_current("docs-http-auth-policy") %>>
 							<a href="/docs/http/sys-policy.html">/sys/policy</a>
 						</li>
+
+						<li<%= sidebar_current("docs-http-auth-capabilities") %>>
+							<a href="/docs/http/sys-capabilities.html">/sys/capabilities</a>
+						</li>
+
+						<li<%= sidebar_current("docs-http-auth-capabilities-self") %>>
+							<a href="/docs/http/sys-capabilities-self.html">/sys/capabilities-self</a>
+						</li>
 					</ul>
 				</li>