From 0fd7eaa248b035ae67480a4eb761a7c36c21cfb4 Mon Sep 17 00:00:00 2001
From: Dolph Mathews <dolph.mathews@gmail.com>
Date: Mon, 27 Jan 2014 17:49:05 -0600
Subject: [PATCH] Add example for domain-scoped authentication

Change-Id: I6a97ce0702dbe29fa2492f876d453273b8c52ae0
Closes-Bug: 1269160
---
 .../v3/src/markdown/identity-api-v3.md        | 55 +++++++++++++++++--
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/openstack-identity-api/v3/src/markdown/identity-api-v3.md b/openstack-identity-api/v3/src/markdown/identity-api-v3.md
index 385258d2..1c28b688 100644
--- a/openstack-identity-api/v3/src/markdown/identity-api-v3.md
+++ b/openstack-identity-api/v3/src/markdown/identity-api-v3.md
@@ -1304,10 +1304,10 @@ combination with request to change authorization scope.
 
 ##### Scope: `scope`
 
-An authorization scope, including either a project or domain, can be optionally
-specified as part of the request. If both a domain and a project are specified,
-an HTTP 400 Bad Request will be returned, as a token cannot be simultaneously
-scoped to both a project and domain.
+An authorization scope, including either a `project` or `domain`, can be
+optionally specified as part of the request. If both a `domain` and a `project`
+are specified, an HTTP 400 Bad Request will be returned, as a token cannot be
+simultaneously scoped to both a `project` and `domain`.
 
 A `project` may be specified by either `id` or `name`. An `id` is sufficient to
 uniquely identify a `project`. Example request:
@@ -1387,6 +1387,53 @@ Alternatively, a `domain` `name` may be used to uniquely identify the
         }
     }
 
+A `domain` scope may be specified by either the domain's `id` or `name` with
+equivalent results. Example request specifying a domain by `id`:
+
+    {
+        "auth": {
+            "identity": {
+                "methods": [
+                    "password"
+                ],
+                "password": {
+                    "user": {
+                        "id": "0ca8f6",
+                        "password": "secrete"
+                    }
+                }
+            },
+            "scope": {
+                "domain": {
+                    "id": "1789d1"
+                }
+            }
+        }
+    }
+
+Example request specifying a domain by `name`:
+
+    {
+        "auth": {
+            "identity": {
+                "methods": [
+                    "password"
+                ],
+                "password": {
+                    "user": {
+                        "id": "0ca8f6",
+                        "password": "secrete"
+                    }
+                }
+            },
+            "scope": {
+                "domain": {
+                    "name": "example.com"
+                }
+            }
+        }
+    }
+
 If neither a `project` nor a `domain` is provided for `scope`, and the
 authenticating `user` has a defined default project (the user's
 `default_project_id` attribute), then this will be treated as the preferred