Fix incorrect request format for rescoping a token

The request format for rescoping a token indicated that the
"token" was a string. It's actually an object where the token
id is in the "id" attribute.

The fix is to change the documentation so that it's more obvious
that the "token" is an object that contains an "id" attribute.

This will make it easier for users because they won't try to pass
the token as a string rather than in the "id" attribute.

Change-Id: I2865caa73418e6b26e3ac17686c430b910db4444
Closes-Bug: #1292844

api-ref/src/wadls/identity-api/src/v2.0/samples/auth_token_request.json

@@ -0,0 +1,8 @@
+{
+   "auth": {
+      "tenantName": "demo",
+      "token": {
+         "id": "cbc36478b0bd8e67e89469c7749d4127"
+      }
+   }
+}

api-ref/src/wadls/identity-api/src/v2.0/samples/auth_token_request.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<auth xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns="http://docs.openstack.org/identity/api/v2.0"
+  tenantName="demo">
+  <token id="cbc36478b0bd8e67e89469c7749d4127"/>
+</auth>

api-ref/src/wadls/identity-api/src/v2.0/wadl/identity-admin.wadl

@@ -373,8 +373,14 @@
             <param name="token" style="plain" required="false"
                 type="xsd:string">
                 <wadl:doc xmlns="http://docbook.org/ns/docbook"
-                    ><para>A token. Required if you do not provide
+                    ><para>A <code>token</code> object. Required if you do not
-                        password credentials.</para></wadl:doc>
+                        provide password credentials.</para></wadl:doc>
+            </param>
+            <param name="id" style="plain" required="false"
+                type="xsd:string">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    ><para>The token ID. This is a required field in the
+                    <code>token</code> object.</para></wadl:doc>
             </param>
             <representation mediaType="application/json"
                 element="identity:auth">
@@ -396,6 +402,26 @@
                     </xsdxt:sample>
                 </wadl:doc>
             </representation>
+            <representation mediaType="application/json"
+                element="identity:auth">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook">
+                    <xsdxt:sample
+                        title="Authenticate with token: JSON request">
+                        <xsdxt:code
+                            href="../samples/auth_token_request.json"/>
+                    </xsdxt:sample>
+                </wadl:doc>
+            </representation>
+            <representation mediaType="application/xml"
+                element="identity:auth">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook">
+                    <xsdxt:sample
+                        title="Authenticate with token: XML request">
+                        <xsdxt:code
+                            href="../samples/auth_token_request.xml"/>
+                    </xsdxt:sample>
+                </wadl:doc>
+            </representation>
         </request>
         <response status="200 203">
             <param name="access" style="plain" required="true"

api-ref/src/wadls/identity-api/src/v2.0/wadl/identity.wadl

@@ -267,8 +267,14 @@
             <param name="token" style="plain" required="false"
                 type="xsd:string">
                 <wadl:doc xmlns="http://docbook.org/ns/docbook"
-                        ><para>A token. Required if you do not provide
+                    ><para>A <code>token</code> object. Required if you do not
-                        password credentials.</para></wadl:doc>
+                        provide password credentials.</para></wadl:doc>
+            </param>
+            <param name="id" style="plain" required="false"
+                type="xsd:string">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    ><para>The token ID. This is a required field in the
+                    <code>token</code> object.</para></wadl:doc>
             </param>
             <representation mediaType="application/json"
                 element="identity:auth">
@@ -290,6 +296,26 @@
                     </xsdxt:sample>
                 </wadl:doc>
             </representation>
+            <representation mediaType="application/json"
+                element="identity:auth">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook">
+                    <xsdxt:sample
+                        title="Authenticate with token: JSON request">
+                        <xsdxt:code
+                            href="../samples/auth_token_request.json"/>
+                    </xsdxt:sample>
+                </wadl:doc>
+            </representation>
+            <representation mediaType="application/xml"
+                element="identity:auth">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook">
+                    <xsdxt:sample
+                        title="Authenticate with token: XML request">
+                        <xsdxt:code
+                            href="../samples/auth_token_request.xml"/>
+                    </xsdxt:sample>
+                </wadl:doc>
+            </representation>
         </request>
         <response status="200 203">
             <param name="access" style="plain" required="true"