Signing agreements

After creating identities for users and/or elements in your system, a Verifiable Contractual Agreement (VCA) can be used to define how data should be used and exchanged. These VCAs are a JSON encoding of a legal data sharing agreement and can represent any access and sharing permissions and restrictions needed in your system.

Before data is shared, the entities (users or elements in your system) both sign the agreement cryptographically using the keys associated with their ID.

NOTE: If JLINC is being used for auditing purposes only, this is an optional step and the "nil agreement" of `00000000-0000-0000-0000-000000000000 can be used for any future data events.

First, use the produce endpoint to create and save an agreement that is valid once signed by entity 1. This call then cryptographically signs it, makes an audit record, signs that, and delivers it to the archive service. In this example, we are using the same server for both the data record and the audit/archive record, however normally this would be a local service for data, and a remote service for auditing.

const agreement = (await axios.post(
    `https://api-test.jlinc.io/api/v1/data/agreement/produce`,
    {
        data: {
            references: [`https://sisa.jlinc.org/v1/34020c5fb59ebc6507ebca4eb38090aec1097c6aec8d2ae2250ddfed4b4aa63c`],
            permitted: ['data-sharing'],
            prohibited: ['non-delegable'],
            shortNames: [system.didDoc.shortName], // Any required signature before the agreement is valid
            validRoles: [
                'system',
                'user',
                'third-party',
            ],
        },
        shortName: system.didDoc.shortName, // Sign this agreement with this entity
        role: 'system', // Sign as this role
        archive: {
            url: 'https://api-test.jlinc.io',
            key: archiveToken,
        },
    },
    {
        headers: {
            'Authorization': `Bearer ${token}`,
        }
    }
)).data;
console.log(`Agreement: ${JSON.stringify(agreement, null, 4)}\n`);

Normally, any calls to get API endpoints require the API key of the user who owns the agreement. However, if you wish for agreements to be resolvable for transparency, add a public: true to the data payload and any API key will be able to resolve the agreement with a get API call.

Next, for any other entity's engagement in the agreement, such as a user in this example, they must sign the agreement using the process endpoint.

const processedUserAgreement = (await axios.post(
    `https://api-test.jlinc.io/api/v1/data/agreement/process`,
    {
        agreementId: agreement.created.agreementId,
        shortName: user.didDoc.shortName,
        role: 'user',
        archive: {
            url: config.archiveUrl,
            key: archiveToken,
        },
    },
    {
        headers: {
            'Authorization': `Bearer ${token}`,
        }
    }
)).data;
console.log(`User processed agreement: ${JSON.stringify(processedUserAgreement, null, 4)}\n`);