Skip to content

Latest commit

 

History

History
467 lines (318 loc) · 17.3 KB

API.md

File metadata and controls

467 lines (318 loc) · 17.3 KB

Data Bunker API

ParanoidGuy Databunker is a special GDPR compliant database for personal & private information.

Latest API is available On Postman:

https://documenter.getpostman.com/view/11310294/Szmcbz32


User Api

User API is used to store, change and retrieve user personal information out of Databunker.

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. If the request is successful it returns new user {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}, {phone} and {email} out of POST data or from JSON root level and builds additional hashed indexes for user record.

The {login}, {phone}, {email} values must be unique, otherwise you will get a duplicate user record error. So, for example, you can not create two user records with the same email address.

The following content type supported:

  • application/json
  • application/x-www-form-urlencoded

Example:

Create user by posting data in JSON format:

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 record by posting 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 is an additional user identifier.

For work with semi-trusted environments or 3rd party companies, use shareable record instead of user {token}. Shareable {record} is time bounded.

Get user record

GET /v1/user/{token,login,email,phone}/{identity}

Explanation

This API is used to get user record stored in Databunker. You can lookup user record by {token}, {email}, {phone} or {login} values.

Example:

Fetch user record by {token} value:

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 user record by {login} name:

curl --header "X-Bunker-Token: $XTOKEN" -XGET \
   https://localhost:3000/v1/user/login/user1123
{"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}/{identity}

Explanation

This API is used to update user record. User record can be identified by {token}, {email}, {phone} or {login}. On success, this API call returns success status 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 from user profile by setting it's value to null. For example {"key-to-delete":null}.

Example:

The following command will change user name to "Alex". An Audit event will be generated saving 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":"DAD2474A-E9A7-4BA7-BFC2-C4506880198E"}

Delete user record

DELETE /v1/user/{token,login,email,phone}/{identity}

This command will remove all user records from the database, leaving only user {token} for refference. This API is used to fullfull the customer' right to forget.

In Databunker enterprise version, user record deletion can be delayed as defined by the company policy.

Example:

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

The User App 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/userapps 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"}. Subminiting several times for the same user and app will overwrite previous value.

You can send app data as JSON POST or as regular POST parameters.

Example:

curl -s http://localhost:3000/v1/userapp/token/$TOKEN/shipping \
  -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \
  -d '{"country":"UK","city":"London","address":"221B Baker Street","postcode":"12345","status":"new"}'
{"status":"ok","token":"$TOKEN"}

Update user app record

PUT /v1/userapp/token/{token}/{appname}

Explanation

Update user app record with new values.

Example:

curl -s http://localhost:3000/v1/userapp/token/$TOKEN/shipping -XPUT \
  -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \
  -d '{"status":"delivered"}'
{"status":"ok","token":"$TOKEN"}

Get user app record

GET /v1/userapp/token/{token}/{appname}

Explanation

Returns user app record JSON.

Example:

curl -s http://localhost:3000/v1/userapp/token/$TOKEN/shipping \
  -H "X-Bunker-Token: $XTOKEN"
{"status":"ok","token":"94d12078-18c5-e973-54db-f9aa92790f3f",
  "data":{"address":"221B Baker Street","city":"London","country":"UK","postcode":"12345","status":"delivered"}}

User Session Api

You can use Session API to store and manage user sessions. For example sessions for Web and Mobile applications. You can use session token generated in your application logs instead of clear text user IP, cookies, etc... This information is is considered now as PII.

Session generation API is flexible and you can push any data you wish to save in session record. It can be: user ip, mobile device info, user agent, etc...

Each session record has an expiration period. When the record it is expired, it is automatically deleted.

Resource / HTTP method POST (create) GET (read) PUT (update) DELETE (delete)
/v1/session/phone/{phone} Create new session Get sessions Error Error
/v1/session/email/{email} Create new session Get sessions Error Error
/v1/session/token/{token} Create new session Get sessions Error Error
/v1/session/session/:session Error Get session Error Error

Create user session record

POST /v1/session/{token,login,email,phone}/{identity}

Explanation

This API is used to create new user session and if the request is successful it returns new {session} token.

You can send the data as JSON POST or as regular POST parameters.

Additional parameter is expiration specifies TTL for this session record.

Example:

curl -s http://localhost:3000/v1/session/email/test@securitybunker.io -XPOST \
   -H "X-Bunker-Token: "$DATABUNKER_APIKEY -H "Content-Type: application/json" \
   -d '{"expiration":"3d","clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}'`
{"status":"ok","session":"7a77ffad-2010-4e47-abbe-bcd04509f784"}

Get user session record

GET /v1/session/session/:session

Explanation

This API returns session data.

Example:

curl -s http://localhost:3000/v1/session/session/7a77ffad-2010-4e47-abbe-bcd04509f784 \
   -H "X-Bunker-Token: "$DATABUNKER_APIKEY -H "Content-Type: application/json"`
{"status":"ok","session":"7a77ffad-2010-4e47-abbe-bcd04509f784","when":1576526253,
 "data":{"clientip":"1.1.1.1","info":"email","x-forwarded-for":"2.2.2.2"}}

Get all session records by user identity.

GET /v1/session/{token,login,email,phone}/{identity}

Explanation

This API returns an array of session records for the same user. This command supports paging arguments offset and limit (in URL request).

Example:

curl -s http://localhost:3000/v1/session/phone/4444 \
   -H "X-Bunker-Token: "$DATABUNKER_APIKEY -H "Content-Type: application/json"`
{"status":"ok","count":"20","rows":[
   {"when":1576525605,"data":{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}},
   {"when":1576525605,"data":{"clientip":"1.1.1.1","info":"email","x-forwarded-for":"2.2.2.2"}},
   {"when":1576525660,"data":{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}},
   {"when":1576525660,"data":{"clientip":"1.1.1.1","info":"email","x-forwarded-for":"2.2.2.2"}},
   {"when":1576526129,"data":{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}},
   {"when":1576526130,"data":{"clientip":"1.1.1.1","info":"email","x-forwarded-for":"2.2.2.2"}},
   {"when":1576526253,"data":{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}},
   {"when":1576526253,"data":{"clientip":"1.1.1.1","info":"email","x-forwarded-for":"2.2.2.2"}},
   {"when":1576526291,"data":{"clientip":"1.1.1.1","x-forwarded-for":"2.2.2.2"}},
   {"when":1576526291,"data":{"clientip":"1.1.1.1","info":"email","x-forwarded-for":"2.2.2.2"}}]}

User consent management API

One of the GDPR requirements is the storage of user consent. For example, your customer must approve to receive email marketing information. Data bunker provides an API for user consent storage and management.

When working with consent, Data bunker is using brief value as a consent name. It is unique per user, short consent id. Allowed chars are [a-z0-9-] . Max 64 chars.

Resource / HTTP method POST (create) GET (read) DELETE (delete)
/v1/consent/token/{token}/{brief} Create / Approve Get record Withdraw consent
/v1/consent/login/{login}/{brief} Create / Approve Get record Withdraw consent
/v1/consent/email/{email}/{brief} Create / Approve Get record Withdraw consent
/v1/consent/phone/{phone}/{brief} Create / Approve Get record Withdraw consent
/v1/consent/token/{token} N/A Get records N/A
/v1/consent/login/{login} N/A Get records N/A
/v1/consent/email/{email} N/A Get records N/A
/v1/consent/phone/{phone} N/A Get records N/A
/v1/consents/{brief} N/A Get all users N/A

Create consent record

POST /v1/consent/{token,login,email,phone}/{identity}/{brief}

Explanation

This API is used to store user consent.

POST Body Format

POST Body can contain regular form data or JSON. Here is a table with list of expected parameters.

Parameter (required) Description
status (no) Consent status. Default value is accept. Allowed values: cancel/accept.
message (no) Text message describing consent. If empty brief is displayed.
freetext (no) Free text, used for internal usage.
starttime (no) Date & time to automatically enable this consent. Expected value is in UNIX time format or kind of 10d or 1m, etc...
expiration (no) Consent expiration date. Expected value is in UNIX time format or kind of 10d or 1m, etc...
lawfulbasis (no) Default is consent. It can be: contract-agreement, legal-obligations, etc...
consentmethod (no) Default is api. It can be: phone-consent, contract, app-consent, web-consent, email-consent, etc...
referencecode (no) This can be used as an id of your internal document, contract, etc...
lastmodifiedby (no) Name of the person that last modified this record or customer.

When consent is expired, the status value is changed to expired.

Example:

Create consent by posting JSON:

curl -s http://localhost:3000/v1/consent/email/test@securitybunker.io/send-sms -XPOST \
  -H "X-Bunker-Token: $XTOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mesasge":"Optional long text here."}'
{"status":"ok"}

Create consent by POSTing user key/value fiels as POST fields:

curl -s http://localhost:3000/v1/consent/email/test@securitybunker.io/send-sms -XPOST \
  -H "X-Bunker-Token: $XTOKEN"
  -d 'mesasge=optional+text'
{"status":"ok"}

Withdraw consent record

DELETE /v1/consent/{token,login,email,phone}/{identity}/{brief}

Explanation

This API is used to withdraw user consent.

Example:

Withdraw consent:

curl -s http://localhost:3000/v1/consent/email/test@securitybunker.io/send-sms -XDELETE \
  -H "X-Bunker-Token: $XTOKEN"
{"status":"ok"}

Get a list of all user consent records

GET /v1/consent/{token,login,email,phone}/{identity}

Explanation

This API returns an array of all user consent records. No pagination is supported.

Example:

Fetch by user email:

curl --header "X-Bunker-Token: $XTOKEN" -XGET \
   https://localhost:3000/v1/consent/email/test@securitybunker.io
{"status":"ok","total":2,"rows":[
   {"brief":"send-email-mailgun-on-login","message":"send-email-mailgun-on-login","status":"accept",
   "token":"254d2abf-e927-bdcf-9cb2-f43c3cb7a8fa","mode":"email","when":1576154130,"who":"test@securitybunker.io"},
   {"brief":"send-sms-twilio-on-login","message":"send-sms-twilio-on-login","status":"accept",
   "token":"254d2abf-e927-bdcf-9cb2-f43c3cb7a8fa","mode":"phone","when":1576174683,"who":"4444"}]}

Shareable record API

Sometimes you want to share part of user profile, part fo app data or a part of session details with a partner or to save in logs. Data Bunker provides an easy API to do it.

Each record created has an expiration time. Access to the record data is open to anyone without any access token or without a password.

Resource / HTTP method POST (create) GET (read) PUT (update) DELETE (delete)
/v1/sharedrecord/token/{token} Create new record Error Error Error
/v1/get/{record} Error Get data Error Error

Create shared record request

POST /v1/sharedrecord/token/{token}

Explanation

This API is used to create shared record that is referencing other object in the database (user, user-app, session). It returns {record} token on success.

You can user this token, for example when you need to 3rd party system as a user identity.

POST Body Format

POST Body can contain regular form data or JSON. Expected optional values are message, status.

Parameter Required Description
app No Application name.
partner No Partner name. For example coralogix.
expiration No Record expiration time.
session No Session record token.
fields No List of records to extract. Separated by commas.

Example:

curl -s http://localhost:3000/v1/sharedrecord/token/$TOKEN \
  -H "X-Bunker-Token: $XTOKEN" -H "Content-Type: application/json" \
  -d '{"app":"shipping","fields":"address"}'
{"status":"ok","record":"db90efc7-48fe-9709-891d-a8b295881a9a"}

Get record value.

GET /v1/get/{record}

Return record value.

Example:

curl -s http://localhost:3000/v1/get/$RECORD
{"status":"ok","app":"shipping","data":{"address":"221B Baker Street"}}