mirror of
https://github.com/optim-enterprises-bv/databunker.git
synced 2026-01-13 11:25:23 +00:00
352 lines
11 KiB
Markdown
352 lines
11 KiB
Markdown
# Data Bunker API
|
||
|
||
|
||
**Data Bunker is advanced personal information tokenization and storage service build to comply with GDPR.**
|
||
|
||
---
|
||
|
||
## User Api
|
||
|
||
|
||
| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) |
|
||
| ---------------------- | ---------------- | ------------- | ---------------- | ---------------- |
|
||
| /v1/user | Create new user | Error | Error | Error |
|
||
| /v1/user/token/{token} | Error | Get user | Update user | Delete user PII |
|
||
| /v1/user/login/{login} | Error | Get user | Update user | Delete user PII |
|
||
| /v1/user/email/{email} | Error | Get user | Update user | Delete user PII |
|
||
| /v1/user/phone/{phone} | Error | Get user | Update user | Delete user PII |
|
||
|
||
|
||
## Create user record
|
||
### `POST /v1/user`
|
||
|
||
### Explanation
|
||
|
||
This API is used to create new user record and if the request is successful it returns new `{token}`.
|
||
On the database level, each records is encrypted with it's own key.
|
||
|
||
|
||
### POST Body Format
|
||
|
||
POST Body can contain regular form data or JSON. Data Bunker extracts `{login}`, `{phoen}` and `{email}` out of
|
||
POST data or from JSON first level and builds additional hashed index for user object. These fields, if
|
||
provided must be unique, otherwise you will ge an error. So, you can not create additional user object
|
||
with duplicate email.
|
||
|
||
The following content type supported:
|
||
|
||
* **application/json**
|
||
* **application/x-www-form-urlencoded**
|
||
|
||
|
||
### Example:
|
||
|
||
Create used by posting JSON:
|
||
|
||
```
|
||
curl -s http://localhost:3000/v1/user -XPOST \
|
||
-H "X-Bunker-Token: $XTOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"firstName": "John","lastName":"Doe","email":"user@gmail.com"}'
|
||
{"status":"ok","token":"db80789b-0ad7-0690-035a-fd2c42531e87"}
|
||
```
|
||
|
||
Create user by POSTing user key/value fiels as post parameters:
|
||
|
||
```
|
||
curl -s http://localhost:3000/v1/user -XPOST \
|
||
-H "X-Bunker-Token: $XTOKEN" \
|
||
-d 'firstName=John' \
|
||
-d 'lastName=Doe' \
|
||
-d 'email=user2@gmail.com'
|
||
{"status":"ok","token":"db80789b-0ad7-0690-035a-fd2c42531e87"}
|
||
```
|
||
|
||
**NOTE**: Keep this user token privately as it provides user private information in your system.
|
||
For semi-trusted environments or 3rd party companies, use **shareable identity** instead.
|
||
|
||
|
||
---
|
||
|
||
## Get user record
|
||
### `GET /v1/user/{token,login,email,phone}/{indexValue}`
|
||
|
||
### Explanation
|
||
This API is used to get user PII records. You can lookup user token by **token**, **email**, **phone** or **login**.
|
||
|
||
### Example:
|
||
|
||
Fetch by user token:
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" -XGET \
|
||
https://localhost:3000/v1/user/token/DAD2474A-E9A7-4BA7-BFC2-C4506880198E
|
||
{"status":"ok","token":"DAD2474A-E9A7-4BA7-BFC2-C4506880198E",
|
||
"data":{"fname":"paranoid","lname":"guy","login":"user1123"}}
|
||
```
|
||
|
||
Fetch by "login" name:
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" -XGET \
|
||
https://localhost:3000/v1/user/login/user1
|
||
{"status":"ok","token":"DAD2474A-E9A7-4BA7-BFC2-C4506880198E",
|
||
"data":{"fname":"paranoid","lname":"guy","login":"user1123"}}
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## Update user record
|
||
### `PUT /v1/user/{token,login,email,phone}/{indexValue}`
|
||
|
||
### Explanation
|
||
|
||
This API is used to update user record. You can update user by **token**, **email**, **phone** or **login**.
|
||
This call returns update status on success or error message on error.
|
||
|
||
### POST Body Format
|
||
|
||
POST Body can contain regular form POST data or JSON. When using JSON, you can remove the record by setting it's value to null.
|
||
For example {"key-to-delete":null}.
|
||
|
||
The following content type supported:
|
||
|
||
* **application/json**
|
||
* **application/x-www-form-urlencoded**
|
||
|
||
|
||
### Example:
|
||
|
||
The following command will change user name to "Alex". An Audit event will be generated showing previous and new value.
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" -d 'name=Alex' -XPUT \
|
||
https://localhost:3000/v1/user/token/DAD2474A-E9A7-4BA7-BFC2-C4506880198E
|
||
{"status":"ok","token":"db80789b-0ad7-0690-035a-fd2c42531e87"}
|
||
```
|
||
|
||
---
|
||
|
||
## Delete user by record
|
||
### `DELETE /v1/user/{token,login,email,phone}/{indexValue}`
|
||
|
||
This command will remove all user records from the database, leaving only user token id.
|
||
|
||
```
|
||
curl -header "X-Bunker-Token: $XTOKEN" -XDELETE \
|
||
https://localhost:3000/v1/user/token/DAD2474A-E9A7-4BA7-BFC2-C4506880198E
|
||
{"status":"ok","result":"done"}
|
||
```
|
||
|
||
## User App Api
|
||
|
||
This API is used when you want to store additional information about the user and do not want to
|
||
mix is with profile data. For example shipping information.
|
||
|
||
| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE |
|
||
| --------------------------------- | ------------------- | ----------------- | ------------- | ------- |
|
||
| /v1/userapp/token/:token/:appname | New user app record | Get record | Change record | Delete |
|
||
| /v1/userapp/token/:token | Error | Get user app list | Error | Error |
|
||
| /v1/userapp/list | Error | Get all app list | Error | Error |
|
||
|
||
|
||
## Create user app record
|
||
### `POST /v1/userapp/token/:token/:appname`
|
||
|
||
### Explanation
|
||
|
||
This API is used to create new user app record and if the request is successful it returns `{"status":"ok"}`.
|
||
|
||
|
||
---
|
||
|
||
## User Session Api
|
||
|
||
| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) |
|
||
| ---------------------------- | ------------------ | -------------- | -------------- | --------------- |
|
||
| /v1/session/token/:token | Create new session | Get sessions | Error | Error |
|
||
| /v1/session/session/:session | Error | Get session | Error?? | Error?? |
|
||
| /v1/session/clientip/:ip | Error | Get sessions | Error | Error |
|
||
|
||
|
||
## Create user session record
|
||
### `POST /v1/session/token/:token`
|
||
|
||
### Explanation
|
||
|
||
This API is used to create new user session and if the request is successful it returns new `{session}`.
|
||
You can now use this id in your logs instead of user IP and browser user-agent info, etc...
|
||
|
||
Our API supports generation of session tokens based on the following information:
|
||
user ip, mobile device info, user agent, etc...
|
||
|
||
You can send the data as JSON POST or as regular POST parameters when working with this API.
|
||
|
||
## Get user session record
|
||
### `GET /v1/session/session/:session`
|
||
|
||
### Explanation
|
||
|
||
This API returns session data.
|
||
|
||
|
||
## Get session records by user token.
|
||
### `GET /v1/session/token/:token`
|
||
|
||
### Explanation
|
||
|
||
This API returns an array of sessions of the same user.
|
||
|
||
## Get session records by ip address.
|
||
### `GET /v1/session/clientip/:ipaddress`
|
||
|
||
### Explanation
|
||
|
||
This API returns an array of user sessions by IP address. These sessions can be of different people.
|
||
|
||
---
|
||
|
||
## Passwordless tokens API
|
||
|
||
| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) |
|
||
| ---------------------- | ----------------- | ------------- | ---------------- | ---------------- |
|
||
| /v1/xtoken/:token | Create new record | Error | Error | Error |
|
||
| /v1/xtoken/:token | Error | Get data | Error | Error |
|
||
|
||
router.POST("/v1/xtoken/:token", e.userNewToken)
|
||
router.GET("/v1/xtoken/:xtoken", e.userCheckToken)
|
||
|
||
|
||
---
|
||
|
||
## Shareable token API
|
||
|
||
| Resource / HTTP method | POST (create) | GET (read) | PUT (update) | DELETE (delete) |
|
||
| ---------------------- | ----------------- | ------------- | ---------------- | ---------------- |
|
||
| /v1/shareable/:token | Create new record | Error | Error | Error |
|
||
| /v1/shareable/:token | Error | Get data | Error | Error |
|
||
|
||
|
||
---
|
||
|
||
**TODO-FINISH**
|
||
|
||
|
||
## Temporary user access tokens
|
||
|
||
Sometimes, for example, when working with 3rd party partners or semi-trusted environments, you might
|
||
need to generate a user access token with a specific expiration time. Your partner can retrieve user
|
||
information during this specific time only.
|
||
Afterward, access will be blocked.
|
||
|
||
The following command will generate a token to access user email and name for 7 days:
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" -d 'fields=email,name' -d 'expiration=7d' -d 'partner=sms' \
|
||
https://bunker.company.com/gentokens/DAD2474A-E9A7-4BA7-BFC2-C4506880198E
|
||
```
|
||
|
||
Output:
|
||
|
||
```
|
||
476E41E7-72AD-448A-BB43-7ACDB8C53735
|
||
```
|
||
|
||
|
||
### 3rd party logging
|
||
|
||
Instead of maintaining internal logs, a lot of companies are using 3rd party logging facility like logz or coralogix or something else.
|
||
To improve adherence to GDPR, we build a special feature - generate specific session id for such 3rd party service.
|
||
|
||
When using these uuids in external systems, you basically **pseudonymise personal data**. In addition, in accordance with GDPR Article 5:
|
||
**Principles relating to processing of personal data**. Personal data shall be: (c)
|
||
adequate, relevant and limited to what is necessary in relation to the purposes for which they are processed (‘**data minimisation**’);
|
||
|
||
Here is a command to do it:
|
||
|
||
```
|
||
curl -d 'ip=user@example.com' \
|
||
-d 'user-agent=mozila' \
|
||
-d 'partner=coralogix' \
|
||
-d 'expiration=7d'\
|
||
https://bunker.company.com/gensession/DAD2474A-E9A7-4BA7-BFC2-C4506880198E
|
||
```
|
||
|
||
It will generate a new token, that you can now pass to 3rd party system as a user id.
|
||
|
||
|
||
## User consent management
|
||
|
||
One of the GDPR requirements is the storage of user consent. For example, your customer must approve to receive email marketing information.
|
||
|
||
Using the GDPR language, your customer must give explicit consent to receive marketing information.
|
||
|
||
Consent must be freely given, specific, informed and unambiguous. From GDPR, Article 7, item 3:
|
||
|
||
* **The data subject shall have the right to withdraw his or her consent at any time.**
|
||
* **It shall be as easy to withdraw as to give consent.**
|
||
|
||
To comply with this requirement, we added support to manage user consent. We support the following APIs:
|
||
|
||
|
||
### List granted
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" \
|
||
https://bunker.company.com/consent/DAD2474A-E9A7-4BA7-BFC2-C4506880198E
|
||
```
|
||
|
||
### List all
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" \
|
||
https://bunker.company.com/consent/DAD2474A-E9A7-4BA7-BFC2-C4506880198E?all
|
||
```
|
||
|
||
### Cancel consent
|
||
|
||
```
|
||
curl --header "X-Bunker-Token: $XTOKEN" -XDELETE \
|
||
https://bunker.company.com/consent/DAD2474A-E9A7-4BA7-BFC2-C4506880198E/<consent-id>
|
||
```
|
||
|
||
### User gives consent
|
||
|
||
**TODO**
|
||
|
||
### Easily cancel consent for email marketing
|
||
|
||
For example, for email marketing, users got distracted, when they need to login in order to unsubscribe from the newsletter.
|
||
To simplify this operation, users will be allowed to unsubscribe only using email address without full login operation.
|
||
|
||
### Unlock bunker
|
||
|
||
Run the following command with different keys:
|
||
|
||
```
|
||
bunker unlock **key**
|
||
```
|
||
|
||
Or you can provide multiple keys at once:
|
||
|
||
```
|
||
bunker unlock key1 key2 key3
|
||
```
|
||
|
||
### View lock status
|
||
|
||
```
|
||
bunker status | jq .lock
|
||
```
|
||
|
||
Result:
|
||
|
||
```
|
||
locked
|
||
```
|
||
|
||
|
||
## Audit API
|
||
|