Create consent record and signature
POST/service/individual/record/consent-record
This endpoint is used to create a consent record and signature object. This returns the same objects with the PK defined.
Request
Header Parameters
Individual Id
- application/json
Body
- Array [
- ]
consentRecord objectrequired
A consent record expresses consent (as defined in this building block's specification) to a single DataAgreement. There must be a UNIQUE constraint on (data agreement revision, individual)
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a ConsentRecord that is not yet stored in the database and only exist in transit. Draft ConsentRecords do not have a Revision, but if paired up with a Signature, a valid Revision should be generated.
The DataAgreement to which consent has been given
The Revision of the data agreement which consent has been given to
Copy of the revision hash. The hash is the included in the signature and ensures against tampering with the original agreement.
The Individual who has signed this consent record
True: The individual has positively opted in. False: The individual has explicitly said no (or withdrawn a previous consent).
Possible values: [unsigned, signed]
The state field is used to record state changes after-the-fact. It is maintained by the Consent BB itself. Valid states: unsigned/pending more signatures/signed
A signature that hashes all the values of the consent record and has signed it with the key of the Invidiual, making it verifiable and tamper-proof. TBD: Relation to a Signature schema?
sectorPreferences object[]
Name of the sector
Defines sector is opted in or not
Defines consent record for this sector is last updated
signature objectrequired
A generic signature contains a cryptographic hash of some value, together with a signature created by some private key in another system. Required signing methods: Revision object or another Signature object.
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a Signature that is not yet stored in the database and only exist in transit.
The final payload that is signed, constructed as a JSON serialization of fields {verificationPayload: ..., verificationPayloadHash: ..., verificationMethod: ..., verificationArtifact: ..., verificationSignedBy: ..., verificationJwsHeader, timestamp: ..., signedWithoutObjectReference: ..., objectType: ..., objectReference: ...}. Serialized as a JSON dict. If the signature is generated before anything is stored in the database (and has a PK), then the objectReference should be omitted from the payload but filled in afterwards.
Signature of payload hash, the format of the signature should be specified by either verificationMethod or verificationJwsHeader
A well-known string denoting which method is used. Valid values:
Internally generated serialized version of the data referenced by objectType and objectReference - by extracting and serializing their data as JSON.
Internally generated cryptographic hash of the value to be signed, i.e. the value of verificationPayload
A verification artifact in the form of a scanned object, image, signature etc.
Because an identifier's information may change over time, there is a need to store that information at the time of signing. In case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In case of a non-cryptographic signature, this field could contain a natural individual's names, personal number, email addresses - store a snapshot that binds to the signature at the time of signing. In case of a cryptographic signature, this may be the fingerprint of the individual's public key or in some cases, a token from the user's ID session.
DRAFT FIELD: Specifies the relationship between the authorizing signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate"
Alternative to the verificationMethod, verificationHash and verificationSignature, give a JWS serialized object (RFC7515)
Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof.
Indicates that objectReference was left blank in the serialized version that was signed.
Possible values: [revision, signature]
Name of the schema model that objectReference points to. Values: "signature" or "revision"
A symmetric relation / back reference to the objectType that was signed. We are currently just modelling signing another signature (a chain) or signing a Revision (which can be a revision of a consent record, an agreement, policy etc)
Responses
- 200
- 400
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- ]
consentRecord object
A consent record expresses consent (as defined in this building block's specification) to a single DataAgreement. There must be a UNIQUE constraint on (data agreement revision, individual)
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a ConsentRecord that is not yet stored in the database and only exist in transit. Draft ConsentRecords do not have a Revision, but if paired up with a Signature, a valid Revision should be generated.
The DataAgreement to which consent has been given
The Revision of the data agreement which consent has been given to
Copy of the revision hash. The hash is the included in the signature and ensures against tampering with the original agreement.
The Individual who has signed this consent record
True: The individual has positively opted in. False: The individual has explicitly said no (or withdrawn a previous consent).
Possible values: [unsigned, signed]
The state field is used to record state changes after-the-fact. It is maintained by the Consent BB itself. Valid states: unsigned/pending more signatures/signed
A signature that hashes all the values of the consent record and has signed it with the key of the Invidiual, making it verifiable and tamper-proof. TBD: Relation to a Signature schema?
sectorPreferences object[]
Name of the sector
Defines sector is opted in or not
Defines consent record for this sector is last updated
revision object
A generic revision model captures the serialized contents of any schema's single row. This is then subject to 1) cryptographic signature and 2) auditing.
Aside from "successor" column, a revision should be considered locked.
Revision Id
Possible values: [dataAgreement, policy, dataAgreementRecord]
This was previously called "schema" but for technical reasons should be called "schemaName"
The PK of the object that was serialized.
The object that is serialised.
Indicates that objectId was left blank in serizalizedSnapshot when calculating serializedHash. objectId may be subsequently filled in.
Revisioned data (serialized as JSON) as a dict. Apply JSON Canonicalization Scheme as per IETF RFC 8785. It contains all the fields of the schema except sucessorId, serializedHash, serializedSnapshot.
Hash of serizalizedSnapshot (SHA-1)
Timestamp of when revisioning happened. It should be ISO 8601 UTC date time
Individual Id
Reference to an admin user that has created this revision
If this revision is no longer the latest revision, refer to its successor.
Tamper-resistent artifact from previous record, copied from serializedHash
Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)
signature object
A generic signature contains a cryptographic hash of some value, together with a signature created by some private key in another system. Required signing methods: Revision object or another Signature object.
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a Signature that is not yet stored in the database and only exist in transit.
The final payload that is signed, constructed as a JSON serialization of fields {verificationPayload: ..., verificationPayloadHash: ..., verificationMethod: ..., verificationArtifact: ..., verificationSignedBy: ..., verificationJwsHeader, timestamp: ..., signedWithoutObjectReference: ..., objectType: ..., objectReference: ...}. Serialized as a JSON dict. If the signature is generated before anything is stored in the database (and has a PK), then the objectReference should be omitted from the payload but filled in afterwards.
Signature of payload hash, the format of the signature should be specified by either verificationMethod or verificationJwsHeader
A well-known string denoting which method is used. Valid values:
Internally generated serialized version of the data referenced by objectType and objectReference - by extracting and serializing their data as JSON.
Internally generated cryptographic hash of the value to be signed, i.e. the value of verificationPayload
A verification artifact in the form of a scanned object, image, signature etc.
Because an identifier's information may change over time, there is a need to store that information at the time of signing. In case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In case of a non-cryptographic signature, this field could contain a natural individual's names, personal number, email addresses - store a snapshot that binds to the signature at the time of signing. In case of a cryptographic signature, this may be the fingerprint of the individual's public key or in some cases, a token from the user's ID session.
DRAFT FIELD: Specifies the relationship between the authorizing signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate"
Alternative to the verificationMethod, verificationHash and verificationSignature, give a JWS serialized object (RFC7515)
Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof.
Indicates that objectReference was left blank in the serialized version that was signed.
Possible values: [revision, signature]
Name of the schema model that objectReference points to. Values: "signature" or "revision"
A symmetric relation / back reference to the objectType that was signed. We are currently just modelling signing another signature (a chain) or signing a Revision (which can be a revision of a consent record, an agreement, policy etc)
{
"consentRecord": {
"id": "",
"dataAgreementId": "string",
"dataAgreementRevisionId": "string",
"dataAgreementRevisionHash": "",
"individualId": "string",
"optIn": "",
"state": "",
"signatureId": "string",
"sectorPreferences": [
{
"sector": "",
"optIn": true,
"isLastUpdated": true
}
]
},
"revision": {
"id": "",
"schemaName": "",
"objectId": "",
"objectData": "",
"signedWithoutObjectId": "",
"serizalizedSnapshot": "",
"serializedHash": "",
"timestamp": "",
"authorizedByIndividualId": "string",
"authorizedByOtherId": "",
"successorId": "string",
"predecessorHash": "",
"predecessorSignature": ""
},
"signature": {
"id": "",
"payload": "",
"signature": "",
"verificationMethod": "",
"verificationPayload": "",
"verificationPayloadHash": "",
"verificationArtifact": "",
"verificationSignedBy": "",
"verificationSignedAs": "",
"verificationJwsHeader": "",
"timestamp": "",
"signedWithoutObjectReference": "",
"objectType": "",
"objectReference": ""
}
}
bad input parameter