updated the document for the grant routes

README.md

@@ -103,3 +103,29 @@ the issuer's subject. Resources providers will not have that subject but will
 need to be able to retrieve only public keys that actually belong to the user
 that are trying to validate.
 
+Grants
+------
+Grants represent the list of resources the user has allowed a party to access.
+We store those permissions on the server so that users will not have to grant
+the same privileges multiple times on different machines.
+
+### Saving/Modifying Grants ###
+  * **URL** `:scheme//:hostname/api/issuer@oauth3.org/grants/:sub/:azp`
+  * **Method** `POST`
+  * **Url Params**
+    * `sub`: The [subject](#subject) using the issuer hostname as the `azp`
+    * `azp`: The authorized party the grants are for
+  * **Body Params**
+    * `scope`: A comma separated list of the permissions granted
+
+### Retrieving Grants ###
+  * **URL** `:scheme//:hostname/api/issuer@oauth3.org/grants/:sub/:azp`
+  * **Method** `GET`
+  * **Url Params**
+    * `sub`: The [subject](#subject) using the issuer hostname as the `azp`
+    * `azp`: The authorized party the grants are for
+  * **Response**
+    * `sub`: The same `sub` from the url
+    * `azp`: The same `azp` from the url
+    * `scope`: A comma separated list of the permissions granted
+    * `updatedAt`: The timestamp for the most recent change to the grants

rest.js

@@ -110,12 +110,12 @@ module.exports.create = function (bigconf, deps, app) {
         }
 
         var allowed = token.axs.some(function (acc) {
-          return (req.params.sub || req.query.sub) === (acc.id || acc.ppid || acc.appScopedId);
+          return req.params.sub === (acc.id || acc.ppid || acc.appScopedId);
         });
         if (!allowed) {
           throw new Error("no account pairwise identifier matching '" + req.params.sub + "'");
         }
-        sub = req.params.sub || req.query.sub;
+        sub = req.params.sub;
       }
 
       return sub;
@@ -124,7 +124,7 @@ module.exports.create = function (bigconf, deps, app) {
 
   Grants.restful.get = function (req, res) {
     var promise = Grants.authorizeReq(req).then(function (sub) {
-      return req.Store.get(sub+'/'+(req.params.azp || req.query.azp));
+      return req.Store.get(sub+'/'+req.params.azp);
     }).then(function (result) {
       if (!result) {
         throw new Error('no grants found');
@@ -133,6 +133,7 @@ module.exports.create = function (bigconf, deps, app) {
         sub:   result.sub,
         azp:   result.azp,
         scope: result.scope,
+        updatedAt:  result.updatedAt
       };
     });
 
@@ -163,7 +164,6 @@ module.exports.create = function (bigconf, deps, app) {
   app.post(  '/jwks/:sub', Jwks.restful.saveNew);
 
   app.use(   '/grants', attachSiteStore.bind(null, 'IssuerOauth3OrgGrants'));
-  app.get(   '/grants', Grants.restful.get);
   app.get(   '/grants/:sub/:azp', Grants.restful.get);
   app.post(  '/grants/:sub/:azp', Grants.restful.saveNew);