Skip to main content

Read data agreement

GET 
/service/data-agreement/:dataAgreementId

This endpoint is used to read the data agreement defined by the organisation in consent building block.

Request​

Path Parameters

    dataAgreementId stringrequired

    Unique ID of an object

Responses​

Response Headers
    Schema
    • Array [
      • dataAgreement object

      An agreement contains the specification of a single purpose that can be consented to. A DataAgreement is universal and can be consented to by many individuals through a DataAgreementRecord.

      id string
      version string

      The version of this specification to which a receipt conforms

      controllerId string

      ID of the controller

      controllerUrl stringrequired

      URL of data controller (may be omitted if no data involved)

      controllerName stringrequired

      Name of data controller (may be omitted if no data involved)

      policy objectrequired

      Policy under which this DataAgreement shall be governed. When creating a data agreement, the latest policy can be used to fill the default value, and organisation admin can decide to change it in the data agreement level.

      id string
      name stringrequired

      Name of the policy

      version string

      Version of the policy (it can follow the semver format)

      url stringrequired

      Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time

      jurisdiction string

      Jurisdiction

      industrySector string

      Industry sector

      dataRetentionPeriodDays integer

      Data retention period in days

      geographicRestriction string

      Geographic restriction

      storageLocation string

      Storage location

      thirdPartyDataSharing boolean

      Third party data sharing

      dataAttributes object[]

      Data attributes contain specifications of exactly what is collected.

      purpose stringrequired

      Name of purpose

      purposeDescription stringrequired

      Description of purpose

      lawfulBasis stringrequired

      Possible values: [consent, legal_obligation, contract, vital_interest, public_task, legitimate_interest]

      Lawful basis of the agreement - consent / legal_obligation / contract / vital_interest / public_task / legitimate_interest

      methodOfUse stringrequired

      Possible values: [null, data_source, data_using_service]

      Method of use - null / data_source / data_using_service

      dpiaDate string

      The date on which the DPIA report is generated after a DPIA

      dpiaSummaryUrl string

      The URl providing the DPIA result reports, summary etc that can be verified by any interested parties

      signature object

      Signature of authorising party of DataAgreement (Signatures may be chained in the case of multiple signatures)

      id string

      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 exists in transit.

      payload stringrequired

      The final payload that is signed, constructed as a JSON serialisation of fields {verificationPayload: ..., verificationPayloadHash: ..., verificationMethod: ..., verificationArtifact: ..., verificationSignedBy: ..., verificationJwsHeader, timestamp: ..., signedWithoutObjectReference: ..., objectType: ..., objectReference: ...}. Serialised 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 stringrequired

      Signature of payload hash, the format of the signature should be specified by either verificationMethod or verificationJwsHeader

      verificationMethod stringrequired

      A well-known string denoting which method is used. Valid values: TBD. This might be expanded with supported verification methods. There may be a minimal set of supported methods necessary.

      verificationPayload stringrequired

      Internally generated serialised version of the data referenced by objectType and objectReference - by extracting and serialising their data as JSON

      verificationPayloadHash stringrequired

      Internally generated cryptographic hash of the value to be signed, i.e. the value of verificationPayload

      verificationArtifact string

      A verification artifact in the form of a scanned object, image, signature etc

      verificationSignedBy stringrequired

      Because an identifier's information may change over time, there is a need to store that information at the time of signing. In the case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In the 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 the 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.

      verificationSignedAs string

      DRAFT FIELD: Specifies the relationship between the authorising signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate".

      verificationJwsHeader string

      Alternative to the verificationMethod, verificationHash and verificationSignature, give a JWS serialised object (RFC7515)

      timestamp stringrequired

      Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof

      signedWithoutObjectReference boolean

      Indicates that objectReference was left blank in the serialised version that was signed

      objectType string

      Possible values: [revision, signature]

      Name of the schema model that objectReference points to. Values: "signature" or "revision"

      objectReference string

      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).

      active booleanrequired

      DataAgreement is active and new DataAgreementRecords can be created

      forgettable booleanrequired

      DataAgreementRecord may be deleted when consent is withdrawn, as its existence is not necessary for auditability.

      compatibleWithVersionId string

      WIP: This field indicates that Data Agreement Records may be transferred from this compatible previous revision of the same DataAgreement

      lifecycle stringrequired

      Possible values: [draft, complete]

      WIP: Current Lifecycle state of the DataAgreement. Lifecycle states are used to manage internal workflows and should not be assigned semantic meanings for active Data Agreement Records.

      dataUsingServices undefined[]
      revision object

      A generic revision model captures the serialised contents of any schema's single row. This is then subject to 1) cryptographic signature and 2) auditing.

      Aside from the "successor" column, a revision should be considered locked.

      id stringrequired

      Revision ID

      schemaName stringrequired

      Possible values: [dataAgreement, policy, dataAgreementRecord]

      Previously "schema" but for technical reasons should be called "schemaName"

      objectId stringrequired

      The PK of the object that was serialised

      objectData stringrequired

      The object that is serialised

      signedWithoutObjectId boolean

      Indicates that objectId was left blank in serizalizedSnapshot when calculating serializedHash. objectId may subsequently be filled in.

      serizalizedSnapshot stringrequired

      Revisioned data (sed 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.

      serializedHash stringrequired

      Hash of serizalizedSnapshot (SHA-1)

      timestamp stringrequired

      Timestamp of when revisioning happened. It should be ISO 8601 UTC date time

      authorizedByIndividualId string

      Individual ID

      authorizedByOtherId string

      Reference to an admin user that has created this revision

      successorId string

      If this revision is no longer the latest revision, refer to its successor

      predecessorHash string

      Tamper-resistent artifact from previous record, copied from serializedHash

      predecessorSignature string

      Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)

    • ]
    Loading...
    Last updated on