Merge "Add information about audit_id in token docs"

v3/src/markdown/identity-api-v3.md

@@ -1023,6 +1023,55 @@ Required attributes:
   user for the given token. It is up to the client to look for specific methods
   to determine the total number of factors.
 
+- `audit_ids` (array)
+
+  The `audit_ids` attribute is a list that contains no more than two elements.
+  Each id in the `audit_ids` attribute is a randomly (unique) generated
+  string that can be used to track the token.
+
+  Each token will have its own unique audit identifier as the first element of
+  the array. In the case of a token that was rescoped (exchanged for
+  another token of the same or different scope), there will be a second audit
+  identifier as the second element of the array. This conditional second
+  identifier is the audit id string from the original token (i.e. the first
+  token issued that was not a rescoped token).
+
+  These audit identifiers can be used to track a specific use of token (or
+  chain of tokens) across multiple requests and endpoints without exposing the
+  token id to non-privileged users (e.g. via logs).
+
+  Each audit identifier is a short urlsafe string.
+
+  Example token with `audit_ids` attribute (first element is the token's
+  `audit_id`, second is the `audit_chain_id`):
+
+    {
+        "token": {
+            "expires_at": "2013-02-27T18:30:59.999999Z",
+            "issued_at": "2013-02-27T16:30:59.999999Z",
+            "audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
+            "methods": [
+                "password"
+            ],
+            "user": {
+                "domain": {
+                    "id": "1789d1",
+                    "name": "example.com"
+                }
+                "email": "joe@example.com",
+                "id": "0ca8f6",
+                "name": "Joe"
+            }
+        }
+    }
+
+
+  Tokens issued prior to the inclusion of the audit id code will lack the
+  `audit_ids` attribute. These tokens lacking `audit_ids` will continue to
+  function normally until revoked or expired. All newly issue tokens will
+  have the expected `audit_ids` attribute.
+
+
 Optional attributes:
 
 - `project` (object)
@@ -1136,6 +1185,7 @@ Example entity:
         "token": {
             "expires_at": "2013-02-27T18:30:59.999999Z",
             "issued_at": "2013-02-27T16:30:59.999999Z",
+            "audit_ids": ["VcxU2JYqT8OzfUVvrjEITQ", "qNUTIJntTzO1-XUk5STybw"],
             "methods": [
                 "password"
             ],