Data Debits

What are Data Debits?

Data Debits are the cornerstone of the permission-based, data contracts platform. As the rights to the PDA database are fully owned by the PDA owner, any data acquisition from the database would require permission. When permission is granted, a legitimate contract is agreed upon. This is not the same as consent. The PDA Data Debit process flow enforces a strictly-defined format defining the specific data requested for the owner to review and confirm. Once the data-sharing permissions are given, the contract between the PDA owner and the application provider is logged and Data Debits becomes the only way data can be retrieved from a PDA by anyone other than the owner.
The standard approach is for applications to have access to a single designated namespace. It is possible to have data access to other unrelated namespaces. This can be achieved through a domain-specific data debit mechanism. By default, all applications have read and write access to the namespace specified upon creation but if for example, the application needs to read users' facebook posts, then a data debit will have to be created by the application developer and be accepted by the users.
For example Notables application has a data debit in order to fetch and display the PDA profile information.
Data debit confirmation process is incorporated into the application's Permission Contract request and agreement screen that details which application can access what data. Users have to agree in order for the application or Data Plug to function as intended.
The more general process of creating a Data Debit is:
  • Propose a Data Debit specification to a PDA
  • The PDA owner sees the Data Debit as a pending request, reviews and approves it by confirming it or rejects it.
Dataswift's Platform will log the contract and the Data Debit becomes enabled.
The general process of getting the values from a Data Debit is:
  • Request Data Debit values from the PDA
  • Optional: If any changes are required to the Data Debit request, submit a request to update it

Data debit proposal

The first step in retrieving private data from a PDA is to submit a Data Debit request — POST /api/v2.6/data-debit/$dataDebitKey. Where dataDebitKey can be any valid URL path, however it needs to be unique on the HAT. The request will fail otherwise.
The general schema of a Data Debit is:
1
{
2
"bundle": "[DataBundle]",
3
"conditions": "Optional[DataBundle]",
4
"dataDebitKey": "[String]",
5
"purpose": "[String]",
6
"period": "[Int]",
7
"termsUrl": "[String]",
8
"cancelAtPeriodEnd": "[Boolean]",
9
"requestClientName": "[String]",
10
"requestClientUrl": "[String]",
11
"requestClientLogoUrl": "[String]",
12
"requestClientCallbackUrl": "Optional[String]",
13
"requestApplicationId": "Optional[String]",
14
"requestDescription": "Optional[String]",
15
"start": "[String]"
16
}
Copied!
Parameter
Type
Meaning
dataDebitKey
URL Path
ID of the data debit — any valid URL path
conditions
Data Bundle Object
Optional Data Bundle specification — covered in a separate guide
bundle
Data Bundle Object
Data Bundle specification — covered in a separate guide
start
ISO8601 Date
When data sharing should start
period
Int
The period that the data debit will be active. Value in seconds
purpose
String
The purpose of the data debit. Description of what it does and why it is needed
cancelAtPeriodEnd
Boolean
A value indicating if the data debit will continue after the specified period elapses
termsUrl
URL
A URL for the terms and conditions for that URL
requestClientName
String
The name of the company that created the data debit
requestClientUrl
URL
Company's website URL
requestClientLogoUrl
URL
Company's logo URL
requestClientCallbackUrl
URL
A callback url to be notified for new events
requestApplicationId
URL
Application id of the app requesting the data debit
requestDescription
URL
A description that accompanies the data debit request
As a concrete example, the below request asks for user profile together with location data.
1
{
2
"bundle": {
3
"name": "testbundlename",
4
"bundle": {
5
"profile": {
6
"endpoints": [
7
{
8
"endpoint": "rumpel/profile"
9
}
10
],
11
"limit": 1
12
}
13
}
14
},
15
"dataDebitKey": "testdatadebitkey",
16
"purpose": "This is description of what the data debit is for",
17
"period": 3600,
18
"termsUrl": "termsurl",
19
"cancelAtPeriodEnd": false,
20
"requestClientName": "Data Debit Creator Name",
21
"requestClientUrl": "https://data-debit-creator-website",
22
"requestClientLogoUrl": "https://data-debit-creator-logo-url",
23
"requestApplicationId": "applicationId",
24
"requestDescription": "A short introduction for what the data debit is",
25
"start": "2019-11-06T14:40:44.267Z"
26
}
Copied!
If your request is valid and hence accepted by the PDA, the response will be 201 CREATED status, with the full specification of the data debit in the request body. Please note that both the Data Debit ID and the Bundle name must be unique — Data Debit key identifies the relationship between the user and an application, while the Bundle name identifies the specific data being exchanged. The request will fail otherwise.

Approve Data Debit

An application developer is not authorized to approve data debits, this is managed using an API call: GET /api/v2.6/data-debit/$dataDebitKey/enable. Where $dataDebitKey can be any valid URL path, however it needs to be unique on the PDA, and $bundleName can be any valid name. Specifically, it requires both the Data Debit key and the bundle name to be set to accurately identify the data that is being shared.
1
{
2
"dataDebitKey": "testdatadebitkey",
3
"dateCreated": "2019-11-06T14:43:36+0000",
4
"permissions": [
5
{
6
"dateCreated": "2019-11-06T14:43:40+0000",
7
"purpose": "This is a new description of what the data debit is for",
8
"start": "2019-04-02T09:32:47.000Z",
9
"period": 360000,
10
"cancelAtPeriodEnd": false,
11
"termsUrl": "https://newtermsUrl.com",
12
"bundle": {
13
"name": "testbundlename",
14
"bundle": {
15
"profile": {
16
"endpoints": [
17
{
18
"endpoint": "rumpel/profile"
19
}
20
],
21
"limit": 1
22
}
23
}
24
},
25
"accepted": true,
26
"active": true,
27
"end": null
28
}
29
],
30
"requestClientName": "Data Debit Creator Name",
31
"requestClientUrl": "https://data-debit-creator-website",
32
"requestClientLogoUrl": "https://data-debit-creator-logo-url",
33
"requestApplicationId": "applicationId",
34
"requestDescription": "A short introduction for what the data debit is",
35
"active": true,
36
"accepted": true,
37
"start": "2019-11-06T14:40:44.267Z",
38
"end": null,
39
"permissionsActive": {
40
"dateCreated": "2019-11-06T14:45:53+0000",
41
"purpose": "This is a new description of what the data debit is for",
42
"start": "2019-11-06T14:40:44.267Z",
43
"period": 360000,
44
"cancelAtPeriodEnd": false,
45
"termsUrl": "https://newtermsUrl.com",
46
"bundle": {
47
"name": "testbundlename",
48
"bundle": {
49
"profile": {
50
"endpoints": [
51
{
52
"endpoint": "rumpel/profile"
53
}
54
],
55
"limit": 1
56
}
57
}
58
},
59
"accepted": true,
60
"active": true,
61
"end": null
62
},
63
"permissionsLatest": {
64
"dateCreated": "2019-11-06T14:45:53+0000",
65
"purpose": "This is a new description of what the data debit is for",
66
"start": "2019-11-06T14:40:44.267Z",
67
"period": 360000,
68
"cancelAtPeriodEnd": false,
69
"termsUrl": "https://newtermsUrl.com",
70
"bundle": {
71
"name": "testbundlename",
72
"bundle": {
73
"profile": {
74
"endpoints": [
75
{
76
"endpoint": "rumpel/profile"
77
}
78
],
79
"limit": 1
80
}
81
}
82
},
83
"accepted": true,
84
"active": true,
85
"end": null
86
}
87
}
Copied!

Request Data Debit Values

Once a DataDebit has been both proposed and approved by the PDA owner, it is achieved with a simple GET /api/v2.6/data-debit/$dataDebitKey/values request. Where $dataDebitKey can be any valid URL path, however it needs to be unique on the PDA.
If the data debit is enabled, the response is exactly the same as if you were using Data Bundles directly:
1
{
2
"bundle": {
3
"profile": [
4
{
5
"endpoint": "rumpel/profile",
6
"recordId": "9b136020-372a-4777-81f9-2c4ce6925aea",
7
"data": {
8
"profile": {
9
"website": {
10
"link": "https://example.com",
11
"private": "false"
12
},
13
"nick": {
14
"private": "true",
15
"name": ""
16
},
17
"primary_email": {
18
"value": "[email protected]",
19
"private": "false"
20
}
21
}
22
}
23
}
24
]
25
}
26
}
Copied!
If, on the other hand, you try to request data from a Data Debit that has not been enabled, you will receive an error:
1
{
2
"message": "Bad Request",
3
"cause": "Data Debit testdatadebitkey not enabled"
4
}
Copied!
That's it! You have now successfully received data from a PDA owner using a Data Debit agreement.

Update data debit

Data requirements may change over time. It may be required to update an existing data debit. There are two solutions to this problem:
  1. 1.
    Request a new Data Debit with the updated requirements
  2. 2.
    Update an existing Data Debit
Updating an existing data debit has the benefit of building on an existing relationship with the PDA owner: they see the scope of your request increasing, however they will recognise your application as an application they have already agreed to share data with. The request for updating an existing data debit is: PUT /api/v2.6/data-debit/$dataDebitKey. Where $dataDebitKey can be any valid URL path, however it needs to be unique on the HAT.
The example below requests 10 recent profile records, up from 1 in the previous example:
1
{
2
"bundle": {
3
"name": "testbundlename",
4
"bundle": {
5
"profile": {
6
"endpoints": [
7
{
8
"endpoint": "rumpel/profile"
9
}
10
],
11
"limit": 10
12
}
13
},
14
"dataDebitKey": "testdatadebitkey",
15
"purpose": "This is a new description of what the data debit is for",
16
"period": 360000,
17
"termsUrl": "https://newtermsUrl.com",
18
"cancelAtPeriodEnd": true,
19
"requestClientName": "Data Debit Creator Name",
20
"requestClientUrl": "https://data-debit-creator-website",
21
"requestClientLogoUrl": "https://data-debit-creator-logo-url",
22
"requestApplicationId": "applicationRequestingDataDebitID",
23
"requestDescription": "A short new introduction for what the data debit is",
24
"start": "2019-11-06T14:40:44.267Z"
25
}
26
}
Copied!
Last modified 1yr ago