PRIVAPI NPM CLIENT PACKAGE
npm install @privapi/client-jsPrivapi.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.
Install via NPM:
``javascript`
npm install @privapi.io/client-js
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.
`javascript
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.
PrivapiClient offers the createEncryptedRequest method:
`javascript`
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.
PrivapiClient provides the checkRequestStatus method:
`javascript`
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' | 'ready') indicates the processing status of the request. if 'ready', a response can be picked up by the requestor |
| _pickupLink_ | string | a url to read the response, once it has been provided (status: ready) |
| _clientPublicKey_ | string | your organization's public key |
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).
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.
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).
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
`javascript
// 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.
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.
`javascript
// Construct parameters to send a new request
const params = {
dataSubjectIdentificationReference: '999999',
requestType: 0,
products: ['123456789012345678901234'],
dataSubjectEmail: 'test@example.com',
};
// Create a new request
const newRequestObject = await pc.createEncryptedRequest(params);
`
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.
`javascript
// Construct parameters to send a new request
const params = {
dataSubjectIdentificationReference: '999999',
requestType: 0,
products: ['123456789012345678901234'],
dataSubjectEmail: 'test@example.com',
identificationParameters: ['123456789012345678901234'],
};
// Create a new request
const newRequestObject = await pc.createEncryptedRequest(params);
``