@privapi/client-js

Welcome to the PRIVAPI PORTAL JavaScript client!

Privapi.io offers GDPR subject rights request management as a service. Easily receive, process internally and respond to subject rights requests in a secure and compliant manner. Do not spend your valuable developer resources to reinvent the wheel, don't loose oversight over the requests that you receive, don't be bothered with finding a way to verify the identity of the person sending a request via email or securely transfer personal data to data subjects... simply implement our solution instead!

Visit privapi.io to find out more.

This NPM packages offers JavaScript based client applications a library to connect to the privapi.io API, have the client generate requests, check for request processing status and receive the link to pick up responses.

Installation and usage

Install the package

Install via NPM:

npm install @privapi.io/client-js

Initialize the connection

Each request will be related to an "origin" that requires to be set up within the PRIVAP PORTAL settings section. To access the API and file new requests, you need to create an API key and secret for each origin.

Import the package, create a new object with your api authentication credentials, then fire a new request.

import PrivapiClient from 'privapi.io/client';

const apiKeyId = ''; // Your privapi.io ApiKeyId
const apiKeySecret = ''; // Your privapi.io ApiKeySecret

const pc = new PrivapiClient(apiKeyId, apiKeySecret);

Parameters:

Name	Type	Description
apiKeyId	string	the API key id generated for this specific origin
apiKeySecret	string	the API key secret generated for this specific origin

Note: The parameters ApiKeyId and ApiKeySecret can be obtained from your privapi.io account.

Create a new Request

PrivapiClient offers the createEncryptedRequest method:

Promise createEncryptedRequest( parameters )

Parameters Object:

Name	Type	Required	Description
requestType	number	yes	the type of the request being generated (see table below for possible values)
dataSubjectIdentificationReference	string	yes	a reference to the end user, will be used to find the user in your database (e.g. a unique user Id)
products	array (of strings)	no	an array of strings with the product Ids as configured for your privapi.io client; to benefit from automated / smart responses using PRIVAPI PORTAL, you need to customize products / processes within the app (menu: Settings => Products and Datapoints
dataSubjectEmail	string	no	if additional identification shall be provided by the requestor (via email), email address of requestor must be provided here
identificationParameters	array (of strings)	no	if additional identification shall be provided by the requestor, the required parameter ids must be listed here as an array of strings; identification parameters are created within PRIVAPI PORTAL (menu: Settings => Input Channels => Direct Integration)

Values for the requestType parameter:

value	description
0	Information Request
1	Data Portability
2	Restriction of Processing
3	Objection to processing
4	Rectification Request
5	Erasure Request

Although not required, we recommend to provide the "products" that are used by the requesting individual with the request (if any). This will help us to automatically generate the most appropriate response to the request. Products (or processes) are defined by a distinguished set of personal data that is processed by your organization. E.g. if you provide a payment functionality with your offering, payments could be one of your products, processing name, credit card data, transactions, etc.

Parameters of returned object upon successful creation of request:

Name	Type	Description
newRequestId	string	reference to the created request
secret	string	reference to the created request
requestType	string	indicates the type of request created (see above for a specification)
requestDate	string	represents the ISO timecode of the date when the request was created

If the request was not submitted / created successfully, the promise will fail. It is necessary that you catch the error event and inform your users that the request was not successfully submitted so they do not expect the processing to succeed.

Fetch status of previous requests

PrivapiClient provides the checkRequestStatus method:

Promise checkRequestStatus(requestId)

Parameters:

Name	Type	Description
requestId	string	a reference to the end user, will be used to find the user in your database (e.g. user Id)

Return value: {Object}

Name	Type	Description
newRequestId	string	reference to the created request
status	string	('in progress'
pickupLink	string	a url to read the response, once it has been provided (status: ready)
clientPublicKey	string	your organization's public key

Access responses

Option 1: no additional identification, receive information on response from within your ogranization's digital offering

When no dataSubjectEmail was provided, you can access the response by storing the result object created by the createEncryptedRequest method and then regularly checking for the status using checkRequestStatus method. If property "status" is ready, you construct a link using the pickupLink property, combined with a hashtag (#) and the secret property from the stored result from createEncryptedRequest.

Provide this link to the requestor to access the response.

The hashtag (#) is required as a separator to prevent the server processing the secret as part of the url (keeping end-2-end encryption intact).

Option 2: receive confirmation of receipt via email

When a dataSubjectEmail (and no identificationParameter) was provided with the request, the requestor receives a confirmation email and is asked to set an individual password as a requirement to start processing. Once a response is sent back to the requestor, he receives a notification email with a link to access the response.

Option 3: receive confirmation of receipt and results via email, data subject is required to provide additional details for identification

Same as option 2, but the requestor is not considered identified just because he has access to the digital offer from which the request was sent. The requester is asked to provide the information required by the identificationParameter to allow verification of his identity and subsequently processing of his request.

This option is always recommended if there is either no access to a digital service restricted by authentication or the personal data processed is particularly sensitive (see Art. 9 GDPR, e.g. health records, political or racial data).

Example 1

No additional identification, receive information on response from within your ogranization's digital offering

• Your organization's digital offering needs to store the newRequestObject safely and encrypted in a user's device or an encrypted database
• Your organization's digital offering should check for request status on a regular basis (e.g. on each opening of an app or login to a website); if status is "ready", it should present the pickup link to the user; the link can be opened in any browser, either integrated in your digital offering, on a mobile device or on a desktop browser

// Construct parameters to send a new request
const params = {
	dataSubjectIdentificationReference: '999999',
	requestType: 0,
	products: ['123456789012345678901234'],
};

// Create a new request
const newRequestObject = await pc.createEncryptedRequest(params);

// Fetch current request status and a link to access the response, if available
const result = await pc.checkRequestStatus(
	'f5c8ffde-958f-4a81-a059-972826cadc45'
);

IMPORTANT

• Store the returned object, as this data is required to fetch the request's status and pick up responses.
• Store the returned object returned safely and on a user's device. Use encryption to store the data. It must not be accessible by 3rd parties.
• Remember: anyone with access to this returned data will be able to access responses incl. file attachments with personal data that you may have provided.

Example 2

Receive confirmation of receipt via email

• Requestor will receive an email to confirm receipt of request and is asked to set an individual password
• It is not required for your organization's digital offering to store the results object or regularly check for results; when processing is finished, requestor will receive an email with a link to pick up the response.

// Construct parameters to send a new request
const params = {
	dataSubjectIdentificationReference: '999999',
	requestType: 0,
	products: ['123456789012345678901234'],
	dataSubjectEmail: '[e-mail]',
};

// Create a new request
const newRequestObject = await pc.createEncryptedRequest(params);

Example 3

Additional identification required

• Requestor will receive an email to provide additional identification and set an individual password
• Once information has been provided, processing of request can begin
• When finished, requestor will receive an email with a link to pick up the response.

// Construct parameters to send a new request
const params = {
	dataSubjectIdentificationReference: '999999',
	requestType: 0,
	products: ['123456789012345678901234'],
	dataSubjectEmail: '[e-mail]',
	identificationParameters: ['123456789012345678901234'],
};

// Create a new request
const newRequestObject = await pc.createEncryptedRequest(params);