Verifiable Credentials HTTP API v0.3

3.1.1 OAuth 2.0

When calling a VC HTTP API using OAuth 2.0, the request MUST be made using OAuth 2.0 Rich Authorization Requests to describe the rights requested for the given API. The security parameters relevant for the rights requested for the endpoints in question are encoded as separate objects within the authorization details array.

For example, a client requesting access to the issuing endpoint hosted at https://example.com/issue for the purposes of issuing credentials would combine the security parameters defined in the issuing endpoint as follows:

[
  {
    "type": "https://www.w3c.org/TR/vc-http-api",    "actions": [ "issue" ],    "locations": [ "https://example.com/issue" ],    "datatypes": [ "credential" ]
  }
]

If this is the only request, it is encoded into the OAuth 2.0 Rich Authorization Request as follows:

authorization_details=%5B%7B%22type%22%3A%22https%3A%2F%2Fwww.w3c.org%2FTR%2Fvc-http-api%22%2C%22actions%22%3A%5B%22issue%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fissue%22%5D%2C%22datatypes%22%3A%5B%22credential%22%5D%7D%5D&client_id=...

The OAuth 2.0 scope and resource parameters are not defined for the VC HTTP API, though these parameters MAY be used to combine requests for other APIs with the request for access to the VC HTTP API. Requests for different actions and endpoints MAY be combined into the authorization details request list as different objects.

The access tokens granted from this process MAY be OAuth 2.0 Bearer tokens or any other valid OAuth 2.0 token type.

3.1.2 Grant Negotiation and Authorization Protocol (GNAP)

When calling a VC HTTP API using GNAP , the request MUST be made using the GNAP resource access rights data structures to describe the rights requested for the given API. The security parameters relevant for the rights requested for the endpoints in question are encoded as separate objects within the access array.

For example, a client requesting access to the issuing endpoint hosted at https://example.com/issue for the purposes of issuing credentials would combine the security parameters defined in the issuing endpoint in the following grant request structure:

{  "access_token": {    "access": [
      {
        "type": "https://www.w3c.org/TR/vc-http-api",        "actions": [ "issue" ],        "locations": [ "https://example.com/issue" ],        "datatypes": [ "credential" ]
      }
    ]
  },
  "client": ...
}

This example shows a single request for a single access token, but the same structures apply to multiple requests or multiple access tokens.

GNAP resource reference values are not defined for the VC HTTP API, though such values MAY be used to combine requests for other APIs with the request for access to the VC HTTP API. Requests for different actions and endpoints MAY be combined into the access request list as different objects, or used in separate access tokens.