How It Works

The API takes in a JSON document describing the consent transaction for which the receipt is to be generated. This object includes artifacts such as the presiding jurisdiction for the consent action, an identifier for the party consenting. The output of the API is a signed JSON Web Token (JWT) whose payload consists of all of the input data as well as several additional fields. This JWT is digitally signed by the server.

Digital signature information

The output JWT is signed using the RS256 algorithm defined in JSON Web Signatures. The server's public key is published in JSON Web Key format at:

http://www.consentreceipt.org/api/jwk

Example

An example input to the API is the following JSON object:

      {
        "jurisdiction" : "US",
        "iat": 1443282118,
        "moc": "web form",
        "iss": "http://www.consentreceipt.org/",
        "jti": "cba37edd4e223a44ea0197498663af81c0d68cdf7b5f13975096e34435339e51f86b6bf674f9725632b6f451b4a78c2fb09d3fcd38c978f004fcf99e65bdceab",
        "sub" : "example@example.com" ,

        "data_controller" : {"on_behalf": true, "contact": "Dave Controller", "company": "Data Controller Inc.", "address": "123 St., Place", "email": "dave@datacontroller.com", "phone": "00-123-341-2351"},
        "policy_uri" : "http://example.com/privacy" ,

        "purpose" : [["Bob's Store", "delivery", "financial"]],

        "sensitive" : ["health"] ,

        "sharing" : {sharing:"financial",party_name: "demographic", purpose: "delivery"},

        "notice" : "http://example.com/shortnotice" ,
        "scopes" : "read update"
      }
      

This produces output like the following signed JWT:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdXJpc2RpY3Rpb24iOiJVUyIsIm1vYyI6IndlYiBmb3JtIiwic3ViIjoiZXhhbXBsZUBleGFtcGxlLmNvbSIsIm5vdGljZSI6Imh0dHA6Ly9leGFtcGxlLmNvbS9zaG9ydG5vdGljZSIsInBvbGljeV91cmkiOiJodHRwOi8vZXhhbXBsZS5jb20vcHJpdmFjeSIsImRhdGFfY29udHJvbGxlciI6eyJvbl9iZWhhbGYiOnRydWUsImNvbnRhY3QiOiJEYXZlIENvbnRyb2xsZXIiLCJjb21wYW55IjoiRGF0YSBDb250cm9sbGVyIEluYy4iLCJhZGRyZXNzIjoiMTIzIFN0LiwgUGxhY2UiLCJlbWFpbCI6ImRhdmVAZGF0YWNvbnRyb2xsZXIuY29tIiwicGhvbmUiOiIwMC0xMjMtMzQxLTIzNTEifSwicHVycG9zZSI6W1siQm9iJ3MgU3RvcmUiLCJkZWxpdmVyeSIsImZpbmFuY2lhbCJdXSwic2Vuc2l0aXZlIjpbImhlYWx0aCJdLCJzaGFyaW5nIjp7InNoYXJpbmciOlsiZmluYW5jaWFsIl0sInBhcnR5X25hbWUiOiJkZW1vZ3JhcGhpYyIsInB1cnBvc2UiOiJkZWxpdmVyeSJ9LCJzY29wZXMiOiJyZWFkIHVwZGF0ZSIsImp0aSI6ImNiYTM3ZWRkNGUyMjNhNDRlYTAxOTc0OTg2NjNhZjgxYzBkNjhjZGY3YjVmMTM5NzUwOTZlMzQ0MzUzMzllNTFmODZiNmJmNjc0Zjk3MjU2MzJiNmY0NTFiNGE3OGMyZmIwOWQzZmNkMzhjOTc4ZjAwNGZjZjk5ZTY1YmRjZWFiIiwiaWF0IjoxNDQzMjgyMTE4LCJpc3MiOiJodHRwOi8vd3d3LmNvbnNlbnRyZWNlaXB0Lm9yZy8ifQ.LNY1NdOQg06iI003Mbi56_cnzd3VY7_hO6sn79z65OPXbEU06Budr8juV9HR_EHSCq9C5ungou02b2r15Imp7beIkXJzoVZMdX-_nK-BwaP4hu128TabCUkMAYq0Egk2IQVJV4tsrAjJMbC_l8rE8UDpWDPPNSoV40PCR12_vYeuvTn6Pe8LL9xwcPX0Gz57amqrp4bcs_MUaVfL6L6QH7cPv3MZAnSWBrgGevcQh6m0X0b4jonasyr63falMl3AlCSzSZgwf33ZaPoH8Ioo6zMPEgTtw0EWnSVSBl8Tp06KAqdhFbZ0SPg6DSQoGcNS-vihJDDqmsV_gLv1RmFqQQ

The header portion of the JWT contains:

      {
        "alg": "RS256",
        "typ": "JWT"
      }
      

The payload portion of the JWT contains:

      {
        data_controller: {
          address: "123 St., Place",
          company: "Data Controller Inc.",
          contact: "Dave Controller",
          email: "dave@datacontroller.com",
          on_behalf: true,
          phone: "00-123-341-2351",
        },
        iat: 1443282118,
        iss: "http://www.consentreceipt.org/",
        jti: "cba37edd4e223a44ea0197498663af81c0d68cdf7b5f13975096e34435339e51f86b6bf674f9725632b6f451b4a78c2fb09d3fcd38c978f004fcf99e65bdceab",
        jurisdiction: "US",
        moc: "web form",
        notice: "http://example.com/shortnotice",
        policy_uri: "http://example.com/privacy",
        purpose:[["Bob's Store", "delivery", "financial"]],
        scopes: "read update",
        sensitive: ["health"],
        sharing: {
          party_name: "demographic",
          purpose: "delivery",
          sharing: ["financial"]
        },
        sub: "example@example.com"
      }