# Create consent by email
Source: https://docs.databunker.org/oss/api/consent/create-consent-by-email
oss/api/openapi.yml post /v1/consent/email/{email}/{brief}
Stores consent for a user identified by email
# Create consent by login
Source: https://docs.databunker.org/oss/api/consent/create-consent-by-login
oss/api/openapi.yml post /v1/consent/login/{login}/{brief}
Stores consent for a user identified by login
# Create consent by phone
Source: https://docs.databunker.org/oss/api/consent/create-consent-by-phone
oss/api/openapi.yml post /v1/consent/phone/{phone}/{brief}
Stores consent for a user identified by phone
# Create consent by user token
Source: https://docs.databunker.org/oss/api/consent/create-consent-by-user-token
oss/api/openapi.yml post /v1/consent/token/{token}/{brief}
Stores user consent. The `brief` parameter is a unique consent identifier per user.
Allowed characters: [a-z0-9-], max 64 characters.
# Get consent by email
Source: https://docs.databunker.org/oss/api/consent/get-consent-by-email
oss/api/openapi.yml get /v1/consent/email/{email}/{brief}
Retrieves consent record for a user identified by email
# Get consent by login
Source: https://docs.databunker.org/oss/api/consent/get-consent-by-login
oss/api/openapi.yml get /v1/consent/login/{login}/{brief}
Retrieves consent record for a user identified by login
# Get consent by phone
Source: https://docs.databunker.org/oss/api/consent/get-consent-by-phone
oss/api/openapi.yml get /v1/consent/phone/{phone}/{brief}
Retrieves consent record for a user identified by phone
# Get consent by user token
Source: https://docs.databunker.org/oss/api/consent/get-consent-by-user-token
oss/api/openapi.yml get /v1/consent/token/{token}/{brief}
Retrieves consent record for a user
# List all consents by email
Source: https://docs.databunker.org/oss/api/consent/list-all-consents-by-email
oss/api/openapi.yml get /v1/consent/email/{email}
Returns all consent records for a user identified by email
# List all consents by login
Source: https://docs.databunker.org/oss/api/consent/list-all-consents-by-login
oss/api/openapi.yml get /v1/consent/login/{login}
Returns all consent records for a user identified by login
# List all consents by phone
Source: https://docs.databunker.org/oss/api/consent/list-all-consents-by-phone
oss/api/openapi.yml get /v1/consent/phone/{phone}
Returns all consent records for a user identified by phone
# List all consents by user token
Source: https://docs.databunker.org/oss/api/consent/list-all-consents-by-user-token
oss/api/openapi.yml get /v1/consent/token/{token}
Returns all consent records for a user
# Withdraw consent by email
Source: https://docs.databunker.org/oss/api/consent/withdraw-consent-by-email
oss/api/openapi.yml delete /v1/consent/email/{email}/{brief}
Withdraws consent for a user identified by email
# Withdraw consent by login
Source: https://docs.databunker.org/oss/api/consent/withdraw-consent-by-login
oss/api/openapi.yml delete /v1/consent/login/{login}/{brief}
Withdraws consent for a user identified by login
# Withdraw consent by phone
Source: https://docs.databunker.org/oss/api/consent/withdraw-consent-by-phone
oss/api/openapi.yml delete /v1/consent/phone/{phone}/{brief}
Withdraws consent for a user identified by phone
# Withdraw consent by user token
Source: https://docs.databunker.org/oss/api/consent/withdraw-consent-by-user-token
oss/api/openapi.yml delete /v1/consent/token/{token}/{brief}
Withdraws user consent (GDPR compliance)
# Cancel user expiration
Source: https://docs.databunker.org/oss/api/expiration/cancel-user-expiration
oss/api/openapi.yml post /v1/exp/cancel/{token}
Cancels user account expiration. Requires admin or user token.
# Delete expired user data
Source: https://docs.databunker.org/oss/api/expiration/delete-expired-user-data
oss/api/openapi.yml get /v1/exp/delete/{exptoken}
Confirms deletion of expired user data. This link works in the browser without authentication.
# Get expiration status
Source: https://docs.databunker.org/oss/api/expiration/get-expiration-status
oss/api/openapi.yml get /v1/exp/status/{token}
Retrieves user expiration status. Requires admin or user token.
# Retain user data
Source: https://docs.databunker.org/oss/api/expiration/retain-user-data
oss/api/openapi.yml get /v1/exp/retain/{exptoken}
Cancels expiration and retains user data. This link works in the browser without authentication.
# Start user expiration flow
Source: https://docs.databunker.org/oss/api/expiration/start-user-expiration-flow
oss/api/openapi.yml post /v1/exp/start/{token}
Triggers the user expiration flow for data minimization compliance.
Returns an expiration token that can be used to create retention/deletion links.
# Create session by email
Source: https://docs.databunker.org/oss/api/session/create-session-by-email
oss/api/openapi.yml post /v1/session/email/{email}
Creates a new session for a user identified by email
# Create session by login
Source: https://docs.databunker.org/oss/api/session/create-session-by-login
oss/api/openapi.yml post /v1/session/login/{login}
Creates a new session for a user identified by login
# Create session by phone
Source: https://docs.databunker.org/oss/api/session/create-session-by-phone
oss/api/openapi.yml post /v1/session/phone/{phone}
Creates a new session for a user identified by phone
# Create session by user token
Source: https://docs.databunker.org/oss/api/session/create-session-by-user-token
oss/api/openapi.yml post /v1/session/token/{token}
Creates a new user session and returns a session token.
Sessions can have an expiration TTL specified in the request.
# Delete session
Source: https://docs.databunker.org/oss/api/session/delete-session
oss/api/openapi.yml delete /v1/session/session/{session}
Deletes a session by session token
# Get session data
Source: https://docs.databunker.org/oss/api/session/get-session-data
oss/api/openapi.yml get /v1/session/session/{session}
Retrieves session data by session token
# List sessions by email
Source: https://docs.databunker.org/oss/api/session/list-sessions-by-email
oss/api/openapi.yml get /v1/session/email/{email}
Returns all session records for a user identified by email
# List sessions by login
Source: https://docs.databunker.org/oss/api/session/list-sessions-by-login
oss/api/openapi.yml get /v1/session/login/{login}
Returns all session records for a user identified by login
# List sessions by phone
Source: https://docs.databunker.org/oss/api/session/list-sessions-by-phone
oss/api/openapi.yml get /v1/session/phone/{phone}
Returns all session records for a user identified by phone
# List sessions by user token
Source: https://docs.databunker.org/oss/api/session/list-sessions-by-user-token
oss/api/openapi.yml get /v1/session/token/{token}
Returns an array of all session records for a user
# Backup database
Source: https://docs.databunker.org/oss/api/system/backup-database
oss/api/openapi.yml get /v1/sys/backup
Dumps the internal database in SQL format (SQLite only).
Requires root token authentication.
# Create or update user app record by email
Source: https://docs.databunker.org/oss/api/user-app/create-or-update-user-app-record-by-email
oss/api/openapi.yml post /v1/userapp/email/{email}/{appname}
Stores app-specific data for a user identified by email
# Create or update user app record by login
Source: https://docs.databunker.org/oss/api/user-app/create-or-update-user-app-record-by-login
oss/api/openapi.yml post /v1/userapp/login/{login}/{appname}
Stores app-specific data for a user identified by login
# Create or update user app record by phone
Source: https://docs.databunker.org/oss/api/user-app/create-or-update-user-app-record-by-phone
oss/api/openapi.yml post /v1/userapp/phone/{phone}/{appname}
Stores app-specific data for a user identified by phone
# Create or update user app record by token
Source: https://docs.databunker.org/oss/api/user-app/create-or-update-user-app-record-by-token
oss/api/openapi.yml post /v1/userapp/token/{token}/{appname}
Stores additional information about a user for a specific application.
This is useful for storing app-specific data (e.g., shipping info) separately from profile data.
Submitting multiple times overwrites the previous value.
# Delete user app record by email
Source: https://docs.databunker.org/oss/api/user-app/delete-user-app-record-by-email
oss/api/openapi.yml delete /v1/userapp/email/{email}/{appname}
Removes app-specific data for a user identified by email
# Delete user app record by login
Source: https://docs.databunker.org/oss/api/user-app/delete-user-app-record-by-login
oss/api/openapi.yml delete /v1/userapp/login/{login}/{appname}
Removes app-specific data for a user identified by login
# Delete user app record by phone
Source: https://docs.databunker.org/oss/api/user-app/delete-user-app-record-by-phone
oss/api/openapi.yml delete /v1/userapp/phone/{phone}/{appname}
Removes app-specific data for a user identified by phone
# Delete user app record by token
Source: https://docs.databunker.org/oss/api/user-app/delete-user-app-record-by-token
oss/api/openapi.yml delete /v1/userapp/token/{token}/{appname}
Removes app-specific data for a user
# Get user app record by email
Source: https://docs.databunker.org/oss/api/user-app/get-user-app-record-by-email
oss/api/openapi.yml get /v1/userapp/email/{email}/{appname}
Retrieves app-specific data for a user identified by email
# Get user app record by login
Source: https://docs.databunker.org/oss/api/user-app/get-user-app-record-by-login
oss/api/openapi.yml get /v1/userapp/login/{login}/{appname}
Retrieves app-specific data for a user identified by login
# Get user app record by phone
Source: https://docs.databunker.org/oss/api/user-app/get-user-app-record-by-phone
oss/api/openapi.yml get /v1/userapp/phone/{phone}/{appname}
Retrieves app-specific data for a user identified by phone
# Get user app record by token
Source: https://docs.databunker.org/oss/api/user-app/get-user-app-record-by-token
oss/api/openapi.yml get /v1/userapp/token/{token}/{appname}
Retrieves app-specific data for a user
# Create a new user record
Source: https://docs.databunker.org/oss/api/user/create-a-new-user-record
oss/api/openapi.yml post /v1/user
Creates a new encrypted user record. Databunker extracts `login`, `phone`, and `email` from the request
and builds hashed indexes for lookup. These values must be unique across all users.
# Delete user by email
Source: https://docs.databunker.org/oss/api/user/delete-user-by-email
oss/api/openapi.yml delete /v1/user/email/{email}
Removes all user records, fulfilling GDPR "right to be forgotten"
# Delete user by login
Source: https://docs.databunker.org/oss/api/user/delete-user-by-login
oss/api/openapi.yml delete /v1/user/login/{login}
Removes all user records, fulfilling GDPR "right to be forgotten"
# Delete user by phone
Source: https://docs.databunker.org/oss/api/user/delete-user-by-phone
oss/api/openapi.yml delete /v1/user/phone/{phone}
Removes all user records, fulfilling GDPR "right to be forgotten"
# Delete user by token
Source: https://docs.databunker.org/oss/api/user/delete-user-by-token
oss/api/openapi.yml delete /v1/user/token/{token}
Removes all user records from the database, keeping only the user token for reference.
This fulfills the GDPR "right to be forgotten" requirement.
In the enterprise version, deletion can be delayed according to company policy.
# Get user by email
Source: https://docs.databunker.org/oss/api/user/get-user-by-email
oss/api/openapi.yml get /v1/user/email/{email}
Retrieves a user record by email address
# Get user by login
Source: https://docs.databunker.org/oss/api/user/get-user-by-login
oss/api/openapi.yml get /v1/user/login/{login}
Retrieves a user record by login name
# Get user by phone
Source: https://docs.databunker.org/oss/api/user/get-user-by-phone
oss/api/openapi.yml get /v1/user/phone/{phone}
Retrieves a user record by phone number
# Get user by token
Source: https://docs.databunker.org/oss/api/user/get-user-by-token
oss/api/openapi.yml get /v1/user/token/{token}
Retrieves a user record by their unique token
# Update user by email
Source: https://docs.databunker.org/oss/api/user/update-user-by-email
oss/api/openapi.yml put /v1/user/email/{email}
Updates a user record identified by email address
# Update user by login
Source: https://docs.databunker.org/oss/api/user/update-user-by-login
oss/api/openapi.yml put /v1/user/login/{login}
Updates a user record identified by login name
# Update user by phone
Source: https://docs.databunker.org/oss/api/user/update-user-by-phone
oss/api/openapi.yml put /v1/user/phone/{phone}
Updates a user record identified by phone number
# Update user by token
Source: https://docs.databunker.org/oss/api/user/update-user-by-token
oss/api/openapi.yml put /v1/user/token/{token}
Updates a user record. When using JSON, you can remove fields by setting their value to null.
All changes are logged in the audit trail.
# Architecture
Source: https://docs.databunker.org/oss/get-started/architecture
![Databunker solution]()
**Databunker** is a **vault** for personal records with a twist.
**Vault** products are well-known. For example Hashicorp Vault, or cloud-based tools like AWS Secret Manager or GCP Secret Manager. These tools store binary secret values in encrypted form. These secret values can be database passwords, user private keys, or API tokens. The **vault** knows to encrypt the secret value and store it and provide an API for easy access.
Databunker has another use-case. It can be used to secretly store the whole user record. This record can include a user name, IP address, password, credit card, blockchain keys, healthcare information, etc... Databunker expects to receive the whole user record in JSON format. Databunker stores encrypted records in the back-end database. Out of the personal record, before encryption, Databunker knows to extract the user's email address, phone number, login value if present, and builds a search index. This search index is also hashed on the database level. So, if the attacker gains access to the Databunker back-end database, everything is encrypted or hashed including the search index.
Your code must supply additional user records like first name, last name, user address when calling a Create User API call. These values should be encoded in HTML POST key/value format or JSON format.
When a request is made to create a user record, Databunker performs the following operations:
1. Request sanity check and access token check
2. Normalize email address, phone number, login name
3. Optional strict user schema checks if schema is defined in configuration
4. Calculate secure hash values for email address, phone number, login name
5. Duplicate record validation using using hashed values of email address, phone number, login name
6. Generate a new record UUID to be used as a user token
7. Encrypt the whole user json and save it in backend database (MySQL, PostgreSQL, SQLite)
8. Return newly generated user token to the caller
After creating a new user record, Databunker returns to the caller a user token inn UUID format. That token can be saved in existing database instead of storing personal records or PII/PHI.
![Databunker request flow]()
Databunker provides you an API to lookup user records using the **email address**, **phone number**, **login name** or a **token** received when you create a user record.
Databunker was built with privacy in mind and this is where the product really shines. It provides GDPR compliance, i.e. an audit of changes, handling for user requests like forget-me requests, user request change management, optional DPO approval, etc...
From a technical perspective, the product has many additional features, like the expiration of records, shareable record identities; additional user records, etc...
# Node.js examples
Source: https://docs.databunker.org/oss/get-started/examples
## Examples
1. Passwordless Login with Databunker: [GitHub Repository](https://github.com/securitybunker/databunker-nodejs-passwordless-login)
2. Node.js Example with Passport.js, Magic.Link, and Databunker: [GitHub Repository](https://github.com/securitybunker/databunker-nodejs-example)
3. Secure Session Storage for Node.js Apps: [Detailed Guide](https://databunker.org/use-case/secure-session-storage/#databunker-support-for-nodejs)
## Node.JS modules
1. `@databunker/store` from [https://github.com/securitybunker/databunker-store](https://github.com/securitybunker/databunker-store)
2. `@databunker/session-store` from [https://github.com/securitybunker/databunker-session-store](https://github.com/securitybunker/databunker-session-store)
# Databunker
Source: https://docs.databunker.org/oss/get-started/overview
Databunker is an open-source, Go-based tool for secure personal data tokenization and storage. It can be deployed using Docker Compose or a Kubernetes Helm chart and is designed to help developers protect sensitive data such as PII, PHI, and KYC with minimal effort.
### 💣 The Big Problem with Traditional Database Encryption
Traditional database encryption solutions often provide a false sense of security. While they may encrypt data at rest, they leave critical vulnerabilities:
* **Encryption alone isn’t enough:** Most vendors offer disk-block encryption, ignoring API-level encryption
* **Vulnerable GraphQL Queries:** Unfiltered queries can expose unencrypted data to attackers
* **SQL Injection Risks:** Attackers can retrieve plaintext data through SQL injections
Databunker addresses these gaps with a secure, developer-focused solution for personal data tokenization and storage.
### 🛠️ Databunker Features
* **Tokenization Engine**: Generates UUID tokens for safe data referencing in applications
* **Encrypted Storage**: Secures sensitive records with advanced encryption layer
* **Injection Protection**: Blocks SQL and GraphQL injection attacks by design
* **Secure Indexing**: Uses hash-based indexing for search queries
* **No Plaintext Storage**: Ensures all data is encrypted at rest
* **Restricted Bulk Retrieval**: Disabled by default to prevent data leaks
* **API-Based Access**: Integrates with your backend via a NoSQL-like API
* **Fast Integration**: Set up secure data protection in under 10 minutes
For **credit-card tokenization** or **enterprise security features** check out the Databunker Pro.
### ⚡ Why Databunker?
Databunker provides a robust, open-source vault that eliminates the false sense of security from traditional encryption methods, offering developers a practical way to protect sensitive data.
### 🚀 Deployment & Usage
* **Self-Hosted**: Run on your cloud or on-premises infrastructure
* **Open-Source**: Licensed under MIT for free commercial use
* **GDPR Compliant**: Meets modern privacy regulation requirements
* **High Performance**: Go-powered API ensures fast tokenization and data access
### 🔐 How It Works
1. Store sensitive data in Databunker via API calls
2. Receive UUID tokens to reference data securely in your application
3. Query data using secure, hash-based indexing
4. Benefit from built-in protections against injections and bulk data leaks
Get started with Databunker to secure your sensitive data efficiently.
![Pseudonymized identity]()
# Quickstart
Source: https://docs.databunker.org/oss/get-started/quickstart
## Step 1: Starting the Databunker container
The easiest way to start using Databunker is by running it as a Docker container. Once the container is running, Databunker opens port 3000 and listens for incoming requests.
To launch Databunker with a `DEMO` root access key, ideal for local testing and development, use the following command:
```bash theme={null}
docker run -p 3000:3000 -d --rm --name databunker securitybunker/databunker demo
```
For detailed installation instructions, please refer to the [full installation guide](/doc/install/).
## Step 2: Creating a User Record
Databunker's most popular API request is to store user records. For each new user record, Databunker generates and returns a **user token** in UUID format.
GDPR Relevance:
* Under **GDPR**, this **user token** is referred to as a **pseudonymized identity**. This token can be safely stored in your regular database or logs, as long as **no** additional personal information is stored with it.
* **Pseudonymization** reduces the risk of directly associating personal data with an individual, reinforcing data protection and privacy principles.
* For instance, when you receive a **Right to be forgotten (RTBF) request**, you can remove the personal data from Databunker without affecting other systems.
Use this command to create the user record:
```bash theme={null}
curl -s http://localhost:3000/v1/user \
-X POST -H "X-Bunker-Token: DEMO" \
-H "Content-Type: application/json" \
-d '{"first":"John","last":"Doe","login":"john","phone":"4444","email":"user@gmail.com"}'
```
Output:
```json theme={null}
{ "status": "ok", "token": "eeb04dd7-ecb2-c957-2875-5b98897b21a6" }
```
## Step 3: Retrieving user record
You can retrieve user records using indexed fields, such as **email address**, **login name**, **user token**, or **custom index**.
To fetch customer records by user token, use this command:
```bash theme={null}
curl -s -H "X-Bunker-Token: DEMO" -X GET http://localhost:3000/v1/user/token/eeb04dd7-ecb2-c957-2875-5b98897b21a6
```
You can integrate Databunker into your application's sign-in logic and search for customer records using an email address or login name:
```bash theme={null}
curl -s -H "X-Bunker-Token: DEMO" -X GET http://localhost:3000/v1/user/email/user@gmail.com
curl -s -H "X-Bunker-Token: DEMO" -X GET http://localhost:3000/v1/user/login/john
```
## Full lists of API requests:
For a full list of available requests, please check the [API documentation](https://documenter.getpostman.com/view/11310294/Szmcbz32).
## Step 4: Accessing the Web UI
Databunker includes a built-in web UI. For quick access, we’ve pre-installed Databunker, which you can access at: demo.databunker.org. Use the `DEMO` root token to access the admin panel.
If you deploy Databunker using Docker, this interface is available by default at: localhost:3000. In the demo version, the root token is set to `DEMO` by default.
The **admin** or **Data Protection Officer (DPO)** can use the web interface to:
1. Delete user records to comply with GDPR RTBF "forget me" requests
2. Generate personal data reports and review audit logs
3. Manage personal data processing activities
#### End-User Access:
Databunker's optional customer portal lets users securely access, manage, and update their personal data, supporting GDPR compliance. Key features include secure login, data review, and audit log access. If you created a sample user with the phone number `4444`, as shown in the **Creating a User Record** section, you can use `4444` as both the phone number and password to access the customer portal.
## Step 5: View Node.js code examples
1. Passwordless Login with Databunker: [GitHub Repository](https://github.com/securitybunker/databunker-nodejs-passwordless-login)
2. Node.js Example with Passport.js, Magic.Link, and Databunker: [GitHub Repository](https://github.com/securitybunker/databunker-nodejs-example)
3. Secure Session Storage for Node.js Apps: [Detailed Guide](https://databunker.org/use-case/secure-session-storage/#databunker-support-for-nodejs)
#### Node.js modules
1. `@databunker/store` from [https://github.com/securitybunker/databunker-store](https://github.com/securitybunker/databunker-store)
2. `@databunker/session-store` from [https://github.com/securitybunker/databunker-session-store](https://github.com/securitybunker/databunker-session-store)
# Detailed installation guide
Source: https://docs.databunker.org/oss/installation/overview
## Method 1: Quick installation
* The easiest way to start using Databunker is to deploy it as a standard Docker container with minimal parameters.
* In this setup, it uses an internal **SQLite database** to store encrypted records.
* You can use `DEMO` as a root token when making [API requests](https://documenter.getpostman.com/view/11310294/Szmcbz32)
**Disadvantages:**
* Utilizes a local SQLite database for storing encrypted records
* Lack of security; using `DEMO` as a root access token
* Not recommended for production use
**Run the following commands to start Databunker:**
```bash theme={null}
DATABUNKER_MASTERKEY=`< /dev/urandom LC_CTYPE=C tr -dc 'a-f0-9' | head -c${1:-48};`
echo "DATABUNKER_MASTERKEY value is $DATABUNKER_MASTERKEY"
docker run -p 3000:3000 -d -e DATABUNKER_MASTERKEY=$DATABUNKER_MASTERKEY --name databunker securitybunker/databunker demo
```
The first command generates the encryption key for Databunker's internal database. Be sure to save it for future use.
Open your browser and navigate to [http://localhost:3000/](http://localhost:3000/) to access the product's user interface.
`Note:`
* If the **databunker** container stops, you can restart the service by running `docker start databunker`.
* For production environments, we recommend using a MySQL or PostgreSQL backend instead.
## Method 2: Start Databunker and backend db with docker compose
We prepared a number of scripts and configuration files you can use with Docker Compose. All these files are available in the project's github repository.
Before starting Docker Compose, you need to generate several secret variables used by the containers. These variables include:
* Passwords for MySQL or PostgreSQL databases
* A self-signed SSL certificate
* Databunker root token, and more
For instance, the **DATABUNKER\_ROOTTOKEN** variable will be stored in the `.env/databunker-root.env` file. This value is used as the root token when making Databunker API requests.
The required secret files will be saved in the `.env` directory. Use one of the following scripts from the project's GitHub repository to generate configuration secrets:
* ./generate-mysql-env-files.sh
* ./generate-mysql-demo-env-files.sh
* ./generate-pgsql-env-files.sh
* ./generate-pgsql-demo-env-files.sh
After generating the secrets, you can start Databunker with MySQL using:
```bash theme={null}
docker-compose -f docker-compose-mysql.yml up -d
```
Or, start Databunker with PostgreSQL using:
```bash theme={null}
docker-compose -f docker-compose-pgsql.yml up -d
```
Once started, you can access Databunker by opening your browser and navigating to [http://localhost:3000/](http://localhost:3000/).
## Method 3: Automatic deployment in AWS cloud
We have built Terraform configuration files and Helm charts to deploy Databunker with all required components in AWS. Detailed instructions can be found here:
* [https://github.com/securitybunker/databunker/tree/master/terraform/aws](https://github.com/securitybunker/databunker/tree/master/terraform/aws)
* [https://github.com/securitybunker/databunker/tree/master/charts/databunker](https://github.com/securitybunker/databunker/tree/master/charts/databunker)
## Method 4: Step-by-step production installation
**Start with backend database**
For production installation, you can use **MySQL** or **PostgreSQL** backend databases. This databse will be used to store encrypted user records. For example, you can spin MySQL or PostgreSQL as a container or use a cloud RDS version provided by Google Cloud and AWS, etc...
For example, use the following command to start MySQL server. It will create a `databunkerdb` database for Databunker and create `bunkeruser` for Databunker access to MySQL.
```bash theme={null}
mkdir ~/data
chmod 0777 ~/data
docker run --restart unless-stopped \
-v ~/data:/var/lib/mysql \
-e MYSQL_ROOT_PASSWORD=SuperAdmin4 \
-e MYSQL_DATABASE=databunkerdb \
-e MYSQL_USER=bunkeruser \
-e MYSQL_PASSWORD=BunkerUserPassword4 \
--name=mysqlsrv -d mysql/mysql-server
```
`Note:` make sure to change the passwords above.
**First Databunker initialization step**
Before Databunker can serve user requests it needs to create all tables; generate a master encryption key if not provided; generate root access token if not provided. This process is called **Databunker initialization**. You will need to do it just for the first time.
Run the following command to initialize Databunker:
```bash theme={null}
docker run --rm -it --link mysqlsrv \
-e MYSQL_HOST=mysqlsrv \
-e MYSQL_PORT=3306 \
-e MYSQL_USER_NAME=bunkeruser \
-e MYSQL_USER_PASS=BunkerUserPassword4 \
--entrypoint /bin/sh \
--name dbunker securitybunker/databunker \
-c '/databunker/bin/databunker -init -db databunkerdb -conf /databunker/conf/databunker.yaml'
```
In the command output, you will see the `Master key` and `API Root token` values.
**Start the Databunker service**
After extracting `DATABUNKER_MASTERKEY` you can start the Databunker service using the following command:
```bash theme={null}
docker run --restart unless-stopped -d -p 3000:3000 \
--link mysqlsrv -e MYSQL_HOST=mysqlsrv \
-e DATABUNKER_MASTERKEY=8c9e892a1732881e14960f2b0437a720ad01ae47cd23baa7 \
-e MYSQL_PORT=3306 \
-e MYSQL_USER_NAME=bunkeruser \
-e MYSQL_USER_PASS=BunkerUserPassword4 \
--entrypoint /bin/sh \
--name dbunker securitybunker/databunker \
-c '/databunker/bin/databunker -start -db databunkerdb -conf /databunker/conf/databunker.yaml'
```
## Advanced configuration
Databunker uses the `databunker.yaml` configuration file. You can modify this file to set custom email gateway, SMS gateway, service logo, and more.
There are several ways to load a new configuration file in Databunker:
* Build a new Docker container based on Databunker's Dockerfile and include your custom configuration file inside it
* Create a new configuration file and mount it to the Databunker container
Follow these steps to mount an external configuration file:
**Step 1. Download the default configuration file**
Create a `./conf` directory and download the default configuration file in it:
```bash theme={null}
mkdir ~/conf
curl https://raw.githubusercontent.com/securitybunker/databunker/master/databunker.yaml \
-o ~/conf/databunker.yaml
```
**Step 2: Modify the Configuration File**
Edit the configuration file with your changes: **\~/conf/databunker.yaml**
**Step 3: Start the Databunker Container**
Use the following command to start the Databunker container with the custom configuration:
```bash theme={null}
docker run --restart unless-stopped -d -p 3000:3000 -v ~/conf:/databunker/conf \
--link mysqlsrv -e MYSQL_HOST=mysqlsrv \
-e DATABUNKER_MASTERKEY=8c9e892a1732881e14960f2b0437a720ad01ae47cd23baa7 \
-e MYSQL_PORT=3306 \
-e MYSQL_USER_NAME=bunkeruser \
-e MYSQL_USER_PASS=BunkerUserPassword4 \
--entrypoint /bin/sh \
--name dbunker securitybunker/databunker \
-c '/databunker/bin/databunker -start -db databunkerdb -conf /databunker/conf/databunker.yaml'
```
This command starts Databunker with the custom configuration file located in the \~/conf directory.
## SSL certificates
You can generate SSL certificates and place them in the `/databunker/certs` directory in the running container.
Use the following command to generate self-signed certificate:
```bash theme={null}
cd ~
mkdir -p certs
cd certs
openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \
-subj "/e=UK/ST=/L=London/O=Your-company Ltd./CN=databunker.your-company.com" \
-keyout server.key -out server.cer
```
Next, map `/databunker/certs` directory inside container to the **\~/certs/** directory as:
```bash theme={null}
cd ~
docker run --restart unless-stopped -d -p 3000:3000 -v ~/conf:/databunker/conf -v ~/certs:/databunker/certs \
--link mysqlsrv -e MYSQL_HOST=mysqlsrv \
-e DATABUNKER_MASTERKEY=8c9e892a1732881e14960f2b0437a720ad01ae47cd23baa7 \
-e MYSQL_PORT=3306 \
-e MYSQL_USER_NAME=bunkeruser \
-e MYSQL_USER_PASS=BunkerUserPassword4 \
--entrypoint /bin/sh \
--name dbunker securitybunker/databunker \
-c '/databunker/bin/databunker -start -db databunkerdb -conf /databunker/conf/databunker.yaml'
```
**Use certificates generated by Letsencrypt**
Copy Letsencrypt generated file **privkey.pem** to \~/certs/server.key
Copy Letsencrypt generated file **fullchain.pem** file to \~/certs/server.cer
## Create a test record
You can download and run a small test script that will create a user record, user app record, user consent, etc...
```bash theme={null}
curl https://raw.githubusercontent.com/securitybunker/databunker/master/create-test-user.sh -o test.sh
chmod 755 ./test.sh
./test.sh
```
### Built-in web UI
You can now open browser at [http://localhost:3000/](http://localhost:3000/)
Use the following account details:
Email: [test@securitybunker.io](mailto:test@securitybunker.io)
Phone: 4444
Code: 4444
# Conditional Role-Based Access Control (CRBAC)
Source: https://docs.databunker.org/pro/administration/access-control
**Conditional Role-Based Access Control (CRBAC)** is an advanced access control system that extends traditional Role-Based Access Control (RBAC) by introducing dynamic conditions that determine access rights.
CRBAC is particularly useful for businesses that need to comply with various privacy laws, such as:
1. **DPDPA** (India's Digital Personal Data Protection Act)
2. **FERPA** (Family Educational Rights and Privacy Act in the USA), which governs student education records
3. **GDPR** (General Data Protection Regulation in the EU)
With Databunker Pro, customers can easily implement solutions that align with these regulations, ensuring secure and compliant PII management.
## Key Features of CRBAC
* **Hierarchical Access Control:** Supports parent-child relationships in data access, enabling fine-grained permissions.
* **Context-Aware Policies:** Defines access based on specific attributes like user roles, organizational structures, and compliance requirements.
* **Dynamic Consent Enforcement:** Incorporates consent management for accessing PII.
* **Group-Based Roles:** Databunker supports groups of users, where each member within a group can have distinct roles. For instance, in an educational group, roles like **Teacher** and **Student** can be assigned, or in a family group, roles such as **Parent** and **Child**.
* **Similar to AWS IAM Policies:** Uses a declarative approach to grant or deny access based on conditions.
## Policy Structure
CRBAC policies resemble AWS IAM policies, defining **who** (principale) can perform **what** (actions) on **which** (resources) under **which conditions**.
### Example Policy: Parent-Child Relationship Enforcement
In Databunker Pro, you can create a custom group for family members. Within this group, parents will have read and write access to their child's information.
You can use the following policy to grant parents access to their child's PII and consent information.
```json theme={null}
{
"Effect": "Allow",
"Principal": { "Role": "parent" },
"Action": ["UserGet", "UserUpdate", "BulkListGroupUsers"],
"Resource": [
"${target_group_members:role/child}.profile",
"${target_group_members:role/child}.consent"
],
"Condition": {
"StringEquals": {
"${principal_group_id}": "${target_group_id}"
}
}
}
```
### Example Policy: Teacher-Parent Access
This policy will grant to a teacher entity access to the student's parent information.
```json theme={null}
{
"Effect": "Allow",
"Principal": { "Role": "teacher" },
"Action": ["UserGet", "BulkListGroupUsers"],
"Resource": [
"${target_group_members:role/parent}.profile.name",
"${target_group_members:role/parent}.profile.phone"
],
"Condition": {
"ListIntersect": {
"${principal_group_members:role/student}": "${target_group_members:role/child}"
}
}
}
```
## Why Choose CRBAC?
1. **Compliance-Ready:** CRBAC ensures organizations meet legal and regulatory requirements, including FERPA and DPDPA.
2. **Dynamic Access Control:** Unlike static RBAC, CRBAC adapts access rights based on real-time conditions.
3. **Fine-Grained Permissions:** Allows precise control over PII data access, reducing the risk of unauthorized exposure.
## Implementing CRBAC with Databunker Pro
Databunker Pro simplifies CRBAC implementation by providing:
1. Built-in support for conditional access policies
2. Secure PII storage with compliance enforcement
3. A developer-friendly API for managing role-based conditions
By leveraging **Databunker Pro**, organizations can seamlessly enforce FERPA-compliant data access policies while maintaining flexibility for other regulatory frameworks.
## Conclusion
Conditional Role-Based Access Control (CRBAC) is essential for organizations handling sensitive PII under strict compliance regulations. With Databunker Pro, businesses can implement secure, scalable, and regulation-compliant access control mechanisms tailored to their needs.
# Encryption key rotation
Source: https://docs.databunker.org/pro/administration/key-rotation
Encryption key rotation is a critical process in Databunker Pro to maintain the confidentiality and integrity of sensitive data. The **Wrapping Key**, which encrypts the **Master Key**, is rotated periodically as part of this process to enhance security.
## What is the Master Key?
The **Master Key** is the core encryption key used to protect sensitive data. It is never exposed and is encrypted using a Wrapping Key for additional security.
## What is the Wrapping Key?
The Wrapping Key is a cryptographic key used to encrypt the **Master Key** in Databunker Pro. It acts as an additional layer of protection for the Master Key
## Importance of Key Rotation:
1. **Limiting Key Exposure:** Regular rotation reduces the window of opportunity for potential attackers to compromise the key.
2. **Compliance:** Many security standards and regulations require periodic key rotation.
3. **Mitigating Long-term Attacks:** Rotation helps protect against slow, persistent attempts to break encryption.
## Best Practices:
* Rotate the Wrapping Key at regular intervals (e.g., every 90 days or annually).
* Implement automated reminders for key rotation.
* Maintain a secure log of key rotations for audit purposes.
* Test the rotation process regularly to ensure smooth execution when needed.
## Recovery:
In case the current Wrapping Key is lost or compromised, Databunker Pro allows for recovery using Shamir Key Shares. This ensures that the Master Key can be safely re-encrypted with a new Wrapping Key without exposure.
# Master key
Source: https://docs.databunker.org/pro/administration/master-key
The Master Key is a critical component of Databunker Pro's security architecture. It serves as the primary encryption key for protecting sensitive data stored within the system.
## Key Points:
* The Master Key is automatically generated during the initial setup of Databunker Pro.
* Unlike the open-source version, the Master Key is never exposed in the Pro Version.
* The Master Key is encrypted using a Wrapping Key, adding an extra layer of security.
## Enhanced Security in Pro Version:
In Databunker Pro, the Master Key's security is significantly strengthened compared to the open-source version:
1. **No Exposure:** The Master Key is never revealed or accessible to users or administrators, reducing the risk of key compromise.
2. **Wrapping Key Protection:** The Master Key is encrypted using a Wrapping Key. This means that even if an attacker gains access to the encrypted Master Key, they cannot use it without the Wrapping Key.
3. **Separation of Concerns:** By using a Wrapping Key to encrypt the Master Key, Databunker Pro implements a separation of concerns. This allows for more flexible key management and enhances overall security.
4. **Key Rotation Support:** The use of a Wrapping Key facilitates easier and more secure key rotation processes, allowing for regular updates to the encryption without exposing the Master Key.
5. **Recovery Mechanism:** In case of Wrapping Key loss, the Shamir Key Shares provide a secure way to recover and re-encrypt the Master Key without ever exposing it.
By implementing these additional security measures, Databunker Pro ensures that the Master Key remains secure throughout its lifecycle, significantly reducing the risk of unauthorized access to sensitive data.
# Multi-tenancy
Source: https://docs.databunker.org/pro/administration/multi-tenancy
Databunker Pro supports multi-tenancy, allowing you to manage multiple tenants within a single instance. This document outlines the API endpoints for creating, managing, and interacting with tenants.
**Note:** Multi-tenancy requires PostgreSQL as the backend database and is not supported with MySQL.
## Create Tenant
Creates a new tenant in the Databunker Pro system.
```bash theme={null}
curl -H 'X-Bunker-Token: ROOT-ACCESS-TOKEN' -X POST /v2/TenantCreate \
--data '{"tenantorg":"testorg","tenantname":"testname"}'
```
### Request Body
| Field | Type | Description |
| ----- | ------ | --------------------------------------------------------- |
| name | string | The name of the tenant. Must match the format: \[a-z0-9]+ |
| org | string | The organization slug associated with the tenant |
### Response
| Field | Type | Description |
| ------ | ------ | ------------------------------------- |
| status | string | Operation status ("ok" if successful) |
| xtoken | string | Tenant access token in UUID format |
### Example Response
```json theme={null}
{
"status": "ok",
"xtoken": "TENANT-ACCESS-TOKEN"
}
```
### Notes
* The `TENANT-ACCESS-TOKEN` is a special token to authenticate all tenant related commands. For example create user records.
## Create a Tenant User Account
You have two methods to specify the tenant name: you can either use the `X-Bunker-Tenant` HTTP header or include the tenant name in the hostname. If the `X-Bunker-Tenant` header is missing, Databunker Pro will attempt to retrieve the tenant name from the subdomain in the hostname. If neither option is available, a **default** tenant is used.
Example commands:
```bash theme={null}
curl -H 'X-Bunker-Token: XXXXXXX' \
-H 'X-Bunker-Tenant: TENANT-NAME' \
-H 'Content-Type: application/json' \
-X POST 'http://localhost:3000/v2/UserCreate' \
--data '{"profile":{"firstname":"John","lastname":"Doe","email":"user@email.com","login":"john"}}'
```
```bash theme={null}
curl -H 'X-Bunker-Token: XXXXXXX' \
-X POST https://TENANT-NAME.databunker-domain.com/v2/UserCreate \
--data '{"profile":{"firstname":"John","lastname":"Doe","email":"user@email.com","login":"john"}}'
```
### Notes
* Replace `TENANT-NAME` in the URL with the actual name of the tenant.
* The request body and response format for this endpoint are not provided in the given information. Typically, they would include user details such as name, email, etc., and return a user ID or status.
## Rename Tenant
Renames an existing tenant.
```bash theme={null}
curl -H 'X-Bunker-Token: TENANT-ACCESS-TOKEN' \
-X POST https://old-tenant.databunker-domain.com/v2/TenantUpdate \
--data '{"tenantname":"new-name"}'
```
### Request Body
| Field | Type | Description |
| ----- | ------ | -------------------------------------------------------------- |
| name | string | The new name for the tenant. Must match the format: \[a-z0-9]+ |
### Example Request
```json theme={null}
{
"name": "new-name"
}
```
### Response
| Field | Type | Description |
| ------ | ------ | ------------------------------------- |
| status | string | Operation status ("ok" if successful) |
### Example Response
```json theme={null}
{
"status": "ok"
}
```
### Other commands:
For a full list of API requests, check out the API document.
## General Notes
1. **Tenant Name Format**: Tenant names must follow the format `[a-z0-9]+`. This means they can only contain lowercase letters and numbers.
2. **Tenant-Specific URLs**: After creating a tenant, you'll interact with tenant-specific endpoints using URLs in the format `https://tenant-name.databunker-domain.com/...`.
3. **Authentication**: Most endpoints will require the `TENANT-ACCESS-TOKEN` for authentication. Include this token in the `X-Bunker-Token` header or as specified in the Databunker Pro documentation.
4. **SSL/TLS**: Always use HTTPS for secure communication with the API endpoints.
For more detailed information on request/response formats, additional endpoints, or error handling, please refer to the complete Databunker Pro API documentation.
# Shamir keys
Source: https://docs.databunker.org/pro/administration/shamir-keys
Shamir Keys, based on Shamir's Secret Sharing scheme, provide a robust and secure method for backing up and recovering critical encryption keys in Databunker Pro.
## What are Shamir Keys?
Shamir Keys are a set of cryptographic key shares created using Shamir's Secret Sharing algorithm. This method allows a secret (in this case, the Wrapping Key) to be divided into multiple parts.
## Key Features:
1. **Threshold Scheme:** Databunker Pro uses a 3-out-of-5 scheme, meaning any 3 out of the 5 generated key shares can reconstruct the original secret.
2. **Security:** No single key share contains enough information to reconstruct the secret on its own.
3. **Flexibility:** Allows for distributed key storage among trusted parties or locations.
## Use in Databunker Pro:
* During setup, Databunker Pro generates 5 Shamir Key Shares.
* These shares can be used to recover the Wrapping Key if it's lost or compromised.
* The recovered Wrapping Key can then be used to safely re-encrypt the Master Key.
## Best Practices for Managing Shamir Keys:
1. **Secure Storage:** Store each key share in a different secure location.
2. **Access Control:** Limit access to key shares to authorized personnel only.
3. **Regular Audits:** Periodically verify the integrity and availability of all key shares.
4. **Documentation:** Maintain clear, secure documentation on the location and access procedures for each key share.
5. **Disaster Recovery Planning:** Include Shamir Key recovery procedures in your disaster recovery plans.
## Recovery Process:
1. Gather any 3 of the 5 Shamir Key Shares.
2. Use Databunker Pro's built-in recovery tool to reconstruct the Wrapping Key.
3. Generate a new Wrapping Key and use it to start the Databunker Pro process.
By implementing Shamir Keys, Databunker Pro provides a secure and resilient method for key backup and recovery, ensuring that critical encryption keys can be restored even in worst-case scenarios, without compromising the overall security of the system.
# Accept agreement
Source: https://docs.databunker.org/pro/api/agreement-management/accept-agreement
pro/api/openapi.yml post /v2/AgreementAccept
Records user's acceptance of a legal basis/agreement
# Cancel agreement
Source: https://docs.databunker.org/pro/api/agreement-management/cancel-agreement
pro/api/openapi.yml post /v2/AgreementCancel
Cancels a user's agreement
# Get user agreement
Source: https://docs.databunker.org/pro/api/agreement-management/get-user-agreement
pro/api/openapi.yml post /v2/AgreementGet
Retrieves a specific agreement for a user
# List user agreements
Source: https://docs.databunker.org/pro/api/agreement-management/list-user-agreements
pro/api/openapi.yml post /v2/AgreementListUserAgreements
Lists all agreements for a specific user
# Request agreement cancellation
Source: https://docs.databunker.org/pro/api/agreement-management/request-agreement-cancellation
pro/api/openapi.yml post /v2/AgreementCancelRequest
Creates a cancellation request for an agreement (requires approval)
# Revoke all agreements
Source: https://docs.databunker.org/pro/api/agreement-management/revoke-all-agreements
pro/api/openapi.yml post /v2/AgreementRevokeAll
Revokes all agreements for a specific legal basis
# Create application data for user
Source: https://docs.databunker.org/pro/api/app-data-management/create-application-data-for-user
pro/api/openapi.yml post /v2/AppdataCreate
Stores application-specific data for a user
# Delete application data for user
Source: https://docs.databunker.org/pro/api/app-data-management/delete-application-data-for-user
pro/api/openapi.yml post /v2/AppdataDelete
Deletes application-specific data for a user
# Get application data for user
Source: https://docs.databunker.org/pro/api/app-data-management/get-application-data-for-user
pro/api/openapi.yml post /v2/AppdataGet
Retrieves application-specific data for a user
# List all application names
Source: https://docs.databunker.org/pro/api/app-data-management/list-all-application-names
pro/api/openapi.yml post /v2/AppdataListAppNames
Retrieves a list of all application names in the system
# List app data versions
Source: https://docs.databunker.org/pro/api/app-data-management/list-app-data-versions
pro/api/openapi.yml post /v2/AppdataListVersions
Lists all versions of application data for a user
# List user application names
Source: https://docs.databunker.org/pro/api/app-data-management/list-user-application-names
pro/api/openapi.yml post /v2/AppdataListUserAppNames
Retrieves a list of application names for a specific user
# Request app data update
Source: https://docs.databunker.org/pro/api/app-data-management/request-app-data-update
pro/api/openapi.yml post /v2/AppdataUpdateRequest
Creates an update request for app data (requires approval)
# Update application data for user
Source: https://docs.databunker.org/pro/api/app-data-management/update-application-data-for-user
pro/api/openapi.yml post /v2/AppdataUpdate
Updates application-specific data for a user
# Get specific audit event
Source: https://docs.databunker.org/pro/api/audit-management/get-specific-audit-event
pro/api/openapi.yml post /v2/AuditGetEvent
Retrieves detailed information about a specific audit event
# List user audit events
Source: https://docs.databunker.org/pro/api/audit-management/list-user-audit-events
pro/api/openapi.yml post /v2/AuditListUserEvents
Retrieves audit events for a specific user
# Create access token for role
Source: https://docs.databunker.org/pro/api/authentication/create-access-token-for-role
pro/api/openapi.yml post /v2/XTokenCreateForRole
Creates an access token for a specific role
# Create access token for user
Source: https://docs.databunker.org/pro/api/authentication/create-access-token-for-user
pro/api/openapi.yml post /v2/XTokenCreateForUser
Creates an access token for a specific user
# Create bulk list unlock
Source: https://docs.databunker.org/pro/api/bulk-operations/create-bulk-list-unlock
pro/api/openapi.yml post /v2/BulkListUnlock
Creates an unlock mechanism for bulk list operations
# Delete tokens in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/delete-tokens-in-bulk
pro/api/openapi.yml post /v2/BulkDeleteTokens
Deletes multiple tokens using the bulk unlock mechanism
# List all audit events in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/list-all-audit-events-in-bulk
pro/api/openapi.yml post /v2/BulkListAllAuditEvents
Lists all audit events using the bulk unlock mechanism
# List all user requests in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/list-all-user-requests-in-bulk
pro/api/openapi.yml post /v2/BulkListAllUserRequests
Lists all user requests using the bulk unlock mechanism with pagination
# List all users in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/list-all-users-in-bulk
pro/api/openapi.yml post /v2/BulkListAllUsers
Lists all users using the bulk unlock mechanism with pagination
# List specific users in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/list-specific-users-in-bulk
pro/api/openapi.yml post /v2/BulkListUsers
Lists specific users using the bulk unlock mechanism with user search criteria
# List tokens in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/list-tokens-in-bulk
pro/api/openapi.yml post /v2/BulkListTokens
Lists tokens using the bulk unlock mechanism
# List users in group in bulk
Source: https://docs.databunker.org/pro/api/bulk-operations/list-users-in-group-in-bulk
pro/api/openapi.yml post /v2/BulkListGroupUsers
Lists users in a specific group using the bulk unlock mechanism
# Create connector
Source: https://docs.databunker.org/pro/api/connector-management/create-connector
pro/api/openapi.yml post /v2/ConnectorCreate
Creates a new connector
# Delete connector
Source: https://docs.databunker.org/pro/api/connector-management/delete-connector
pro/api/openapi.yml post /v2/ConnectorDelete
Deletes a connector
# Delete user from connector
Source: https://docs.databunker.org/pro/api/connector-management/delete-user-from-connector
pro/api/openapi.yml post /v2/ConnectorDeleteUser
Deletes user data from a specific connector
# Get table metadata from connector
Source: https://docs.databunker.org/pro/api/connector-management/get-table-metadata-from-connector
pro/api/openapi.yml post /v2/ConnectorGetTableMetaData
Retrieves table metadata from a connector
# Get user data from connector
Source: https://docs.databunker.org/pro/api/connector-management/get-user-data-from-connector
pro/api/openapi.yml post /v2/ConnectorGetUserData
Retrieves user data from a specific connector
# Get user extra data from connector
Source: https://docs.databunker.org/pro/api/connector-management/get-user-extra-data-from-connector
pro/api/openapi.yml post /v2/ConnectorGetUserExtraData
Retrieves additional user data from a specific connector
# List connectors
Source: https://docs.databunker.org/pro/api/connector-management/list-connectors
pro/api/openapi.yml post /v2/ConnectorListConnectors
Lists all configured connectors
# List supported connectors
Source: https://docs.databunker.org/pro/api/connector-management/list-supported-connectors
pro/api/openapi.yml post /v2/ConnectorListSupportedConnectors
Lists all supported connector types
# Update connector
Source: https://docs.databunker.org/pro/api/connector-management/update-connector
pro/api/openapi.yml post /v2/ConnectorUpdate
Updates an existing connector
# Validate connector connectivity
Source: https://docs.databunker.org/pro/api/connector-management/validate-connector-connectivity
pro/api/openapi.yml post /v2/ConnectorValidateConnectivity
Validates connectivity to a connector
# Create multiple tokens in bulk
Source: https://docs.databunker.org/pro/api/format-preserving-tokenization/create-multiple-tokens-in-bulk
pro/api/openapi.yml post /v2/TokenCreateBulk
Creates multiple tokens for sensitive data
# Create token for sensitive data
Source: https://docs.databunker.org/pro/api/format-preserving-tokenization/create-token-for-sensitive-data
pro/api/openapi.yml post /v2/TokenCreate
Creates a token for sensitive data like credit card numbers
# Delete token
Source: https://docs.databunker.org/pro/api/format-preserving-tokenization/delete-token
pro/api/openapi.yml post /v2/TokenDelete
Deletes a token and its associated data
# Get token data
Source: https://docs.databunker.org/pro/api/format-preserving-tokenization/get-token-data
pro/api/openapi.yml post /v2/TokenGet
Retrieves the original data for a given token
# Add user to group
Source: https://docs.databunker.org/pro/api/group-management/add-user-to-group
pro/api/openapi.yml post /v2/GroupAddUser
Adds a user to a specific group with optional role assignment
# Create a new group
Source: https://docs.databunker.org/pro/api/group-management/create-a-new-group
pro/api/openapi.yml post /v2/GroupCreate
Creates a new group for organizing users
# Delete group
Source: https://docs.databunker.org/pro/api/group-management/delete-group
pro/api/openapi.yml post /v2/GroupDelete
Deletes a group
# Get group information
Source: https://docs.databunker.org/pro/api/group-management/get-group-information
pro/api/openapi.yml post /v2/GroupGet
Retrieves information about a specific group
# List all groups
Source: https://docs.databunker.org/pro/api/group-management/list-all-groups
pro/api/openapi.yml post /v2/GroupListAllGroups
Retrieves a list of all groups in the system
# List user groups
Source: https://docs.databunker.org/pro/api/group-management/list-user-groups
pro/api/openapi.yml post /v2/GroupListUserGroups
Lists all groups for a specific user
# Remove user from group
Source: https://docs.databunker.org/pro/api/group-management/remove-user-from-group
pro/api/openapi.yml post /v2/GroupDeleteUser
Removes a user from a specific group
# Update group
Source: https://docs.databunker.org/pro/api/group-management/update-group
pro/api/openapi.yml post /v2/GroupUpdate
Updates an existing group
# Create legal basis
Source: https://docs.databunker.org/pro/api/legal-basis-management/create-legal-basis
pro/api/openapi.yml post /v2/LegalBasisCreate
Creates a new legal basis for data processing
# Delete legal basis
Source: https://docs.databunker.org/pro/api/legal-basis-management/delete-legal-basis
pro/api/openapi.yml post /v2/LegalBasisDelete
Deletes a legal basis
# List legal basis agreements
Source: https://docs.databunker.org/pro/api/legal-basis-management/list-legal-basis-agreements
pro/api/openapi.yml post /v2/LegalBasisListAgreements
Lists all legal basis agreements in the system
# Update legal basis
Source: https://docs.databunker.org/pro/api/legal-basis-management/update-legal-basis
pro/api/openapi.yml post /v2/LegalBasisUpdate
Updates an existing legal basis
# API Overview
Source: https://docs.databunker.org/pro/api/overview
Databunker Pro is a privacy-compliant user data vault and tokenization engine that provides secure storage and management of user data with built-in privacy controls, consent management, and audit capabilities.
## API Documents for AI Assistants
Feed these directly into your LLM or AI coding assistant for accurate, context-aware help when building integrations:
* [OpenAPI Specification](https://github.com/securitybunker/databunkerpro-docs/blob/main/pro/api/openapi.yml)
* [Full documentation (LLM-friendly)](https://docs.databunker.org/llms-full.txt)
## Key Features
* **User Tokenization**: Create, update, and manage user profiles with privacy controls
* **Consent Management**: Handle legal basis and user agreements for GDPR/DPDP compliance
* **Format Preserving Tokenization**: Secure tokenization of sensitive data like credit cards
* **Audit Trail**: Complete audit logging of all data access and modifications
* **Multi-tenant**: Support for multiple tenants with isolated data
* **Role-based Access**: Fine-grained access control with policies and roles
* **Bulk Operations**: Efficient bulk data operations with unlock mechanisms
* **Connector Support**: Integration with external databases and systems
## Authentication
All API calls require authentication via the `X-Bunker-Token` header. For multi-tenant setups, use the `X-Bunker-Tenant` header to specify the tenant context.
### Multi-Tenant Usage
Multi-tenancy is supported when DataBunker Pro is configured to work with PostgreSQL database. **Note:** DataBunker Pro supports both PostgreSQL and MySQL (Percona) as backend databases, but multi-tenancy requires PostgreSQL and is not available with MySQL.
When using DataBunker Pro in a multi-tenant environment:
* **Single Tenant**: Omit the `X-Bunker-Tenant` header (default behavior)
* **Multi-Tenant**: Include `X-Bunker-Tenant: your-tenant-name` header
**Example:**
```bash theme={null}
# Single tenant
curl -X POST http://localhost:3000/v2/UserCreate \
-H "X-Bunker-Token: your-token" \
-d '{"profile":{"login":"user1"}}'
# Multi-tenant
curl -X POST http://localhost:3000/v2/UserCreate \
-H "X-Bunker-Token: your-token" \
-H "X-Bunker-Tenant: acme-corp" \
-d '{"profile":{"login":"user1"}}'
```
## Base URL
The API is available at `/v2/` endpoint with all requests using POST method.
# Create a new policy
Source: https://docs.databunker.org/pro/api/policy-management/create-a-new-policy
pro/api/openapi.yml post /v2/PolicyCreate
Creates a new access control policy
# Get policy information
Source: https://docs.databunker.org/pro/api/policy-management/get-policy-information
pro/api/openapi.yml post /v2/PolicyGet
Retrieves information about a specific policy
# List all policies
Source: https://docs.databunker.org/pro/api/policy-management/list-all-policies
pro/api/openapi.yml post /v2/PolicyListAllPolicies
Retrieves a list of all policies in the system
# Update a policy
Source: https://docs.databunker.org/pro/api/policy-management/update-a-policy
pro/api/openapi.yml post /v2/PolicyUpdate
Updates an existing access control policy
# Create processing activity
Source: https://docs.databunker.org/pro/api/processing-activity-management/create-processing-activity
pro/api/openapi.yml post /v2/ProcessingActivityCreate
Creates a new processing activity
# Delete processing activity
Source: https://docs.databunker.org/pro/api/processing-activity-management/delete-processing-activity
pro/api/openapi.yml post /v2/ProcessingActivityDelete
Deletes a processing activity
# Link processing activity to legal basis
Source: https://docs.databunker.org/pro/api/processing-activity-management/link-processing-activity-to-legal-basis
pro/api/openapi.yml post /v2/ProcessingActivityLinkLegalBasis
Links a processing activity to a legal basis
# List processing activities
Source: https://docs.databunker.org/pro/api/processing-activity-management/list-processing-activities
pro/api/openapi.yml post /v2/ProcessingActivityListActivities
Lists all processing activities in the system
# Unlink processing activity from legal basis
Source: https://docs.databunker.org/pro/api/processing-activity-management/unlink-processing-activity-from-legal-basis
pro/api/openapi.yml post /v2/ProcessingActivityUnlinkLegalBasis
Unlinks a processing activity from a legal basis
# Update processing activity
Source: https://docs.databunker.org/pro/api/processing-activity-management/update-processing-activity
pro/api/openapi.yml post /v2/ProcessingActivityUpdate
Updates an existing processing activity
# Create a new role
Source: https://docs.databunker.org/pro/api/role-management/create-a-new-role
pro/api/openapi.yml post /v2/RoleCreate
Creates a new role for access control
# Link policy to role
Source: https://docs.databunker.org/pro/api/role-management/link-policy-to-role
pro/api/openapi.yml post /v2/RoleLinkPolicy
Links a policy to a role for access control
# Update role
Source: https://docs.databunker.org/pro/api/role-management/update-role
pro/api/openapi.yml post /v2/RoleUpdate
Updates an existing role
# Delete session
Source: https://docs.databunker.org/pro/api/session-management/delete-session
pro/api/openapi.yml post /v2/SessionDelete
Deletes a user session
# Get session
Source: https://docs.databunker.org/pro/api/session-management/get-session
pro/api/openapi.yml post /v2/SessionGet
Retrieves information about a specific session
# List user sessions
Source: https://docs.databunker.org/pro/api/session-management/list-user-sessions
pro/api/openapi.yml post /v2/SessionListUserSessions
Lists all sessions for a specific user
# Upsert session
Source: https://docs.databunker.org/pro/api/session-management/upsert-session
pro/api/openapi.yml post /v2/SessionUpsert
Creates or updates a user session
# Create shared record
Source: https://docs.databunker.org/pro/api/shared-records/create-shared-record
pro/api/openapi.yml post /v2/SharedRecordCreate
Creates a shared record for a user with specific fields
# Get shared record
Source: https://docs.databunker.org/pro/api/shared-records/get-shared-record
pro/api/openapi.yml post /v2/SharedRecordGet
Retrieves a shared record by its UUID
# Generate wrapping key from Shamir's Secret Sharing keys
Source: https://docs.databunker.org/pro/api/system-operations/generate-wrapping-key-from-shamirs-secret-sharing-keys
pro/api/openapi.yml post /v2/SystemGenerateWrappingKey
Generates a wrapping key from three Shamir's Secret Sharing keys
# Get system statistics
Source: https://docs.databunker.org/pro/api/system-operations/get-system-statistics
pro/api/openapi.yml post /v2/SystemGetSystemStats
Retrieves system statistics including user counts, tenant counts, and other metrics
# Get user HTML report
Source: https://docs.databunker.org/pro/api/system-operations/get-user-html-report
pro/api/openapi.yml post /v2/SystemGetUserHTMLReport
Generates an HTML report for a specific user
# Get user report
Source: https://docs.databunker.org/pro/api/system-operations/get-user-report
pro/api/openapi.yml post /v2/SystemGetUserReport
Generates a detailed report for a specific user
# Create a new tenant
Source: https://docs.databunker.org/pro/api/tenant-management/create-a-new-tenant
pro/api/openapi.yml post /v2/TenantCreate
Creates a new tenant for multi-tenant setups
# Get tenant information
Source: https://docs.databunker.org/pro/api/tenant-management/get-tenant-information
pro/api/openapi.yml post /v2/TenantGet
Retrieves information about a specific tenant
# List all tenants
Source: https://docs.databunker.org/pro/api/tenant-management/list-all-tenants
pro/api/openapi.yml post /v2/TenantListTenants
Retrieves a list of all tenants in the system
# Update tenant information
Source: https://docs.databunker.org/pro/api/tenant-management/update-tenant-information
pro/api/openapi.yml post /v2/TenantUpdate
Updates information about a specific tenant
# Approve user request
Source: https://docs.databunker.org/pro/api/user-tokenization/approve-user-request
pro/api/openapi.yml post /v2/UserRequestApprove
Approves a pending user request
# Cancel user request
Source: https://docs.databunker.org/pro/api/user-tokenization/cancel-user-request
pro/api/openapi.yml post /v2/UserRequestCancel
Cancels a pending user request
# Create a new user token
Source: https://docs.databunker.org/pro/api/user-tokenization/create-a-new-user-token
pro/api/openapi.yml post /v2/UserCreate
Creates a new user token with profile information and optional group/role assignment
# Create multiple users in bulk
Source: https://docs.databunker.org/pro/api/user-tokenization/create-multiple-users-in-bulk
pro/api/openapi.yml post /v2/UserCreateBulk
Creates multiple users with their profiles and group information
# Delete user
Source: https://docs.databunker.org/pro/api/user-tokenization/delete-user
pro/api/openapi.yml post /v2/UserDelete
Deletes a user and their associated data
# Get user information
Source: https://docs.databunker.org/pro/api/user-tokenization/get-user-information
pro/api/openapi.yml post /v2/UserGet
Retrieves user information by login, token, or other identifiers
# Get user request
Source: https://docs.databunker.org/pro/api/user-tokenization/get-user-request
pro/api/openapi.yml post /v2/UserRequestGet
Retrieves information about a specific user request
# List user requests
Source: https://docs.databunker.org/pro/api/user-tokenization/list-user-requests
pro/api/openapi.yml post /v2/UserRequestListUserRequests
Lists all requests for a specific user
# List user versions
Source: https://docs.databunker.org/pro/api/user-tokenization/list-user-versions
pro/api/openapi.yml post /v2/UserListVersions
Lists all versions of a user's profile
# Patch user profile using JSON Patch
Source: https://docs.databunker.org/pro/api/user-tokenization/patch-user-profile-using-json-patch
pro/api/openapi.yml post /v2/UserPatch
Updates user profile using JSON Patch operations (RFC 6902)
# Request user deletion
Source: https://docs.databunker.org/pro/api/user-tokenization/request-user-deletion
pro/api/openapi.yml post /v2/UserDeleteRequest
Creates a deletion request for a user (requires approval)
# Request user patch
Source: https://docs.databunker.org/pro/api/user-tokenization/request-user-patch
pro/api/openapi.yml post /v2/UserPatchRequest
Creates a patch request for a user (requires approval)
# Request user update
Source: https://docs.databunker.org/pro/api/user-tokenization/request-user-update
pro/api/openapi.yml post /v2/UserUpdateRequest
Creates an update request for a user (requires approval)
# Search users
Source: https://docs.databunker.org/pro/api/user-tokenization/search-users
pro/api/openapi.yml post /v2/UserSearch
Searches for users using fuzzy matching
# Update user profile
Source: https://docs.databunker.org/pro/api/user-tokenization/update-user-profile
pro/api/openapi.yml post /v2/UserUpdate
Updates user profile information
# Fuzzy search
Source: https://docs.databunker.org/pro/concepts/fuzzy-search
**Fuzzy Search** in Databunker Pro enables intelligent, approximate matching for user records, allowing you to find users even when search terms don't match exactly. This powerful feature is essential for applications that need to handle typos, partial matches, or variations in user data.
## What Problems Does Fuzzy Search Solve?
### 1. **User Experience Enhancement**
* ✅ Handles typos and misspellings in search queries
* ✅ Enables partial matching for incomplete user data
* ✅ Provides intelligent suggestions for user lookup
* ✅ Reduces failed searches due to exact-match requirements
### 2. **Data Quality Challenges**
* ✅ Works with inconsistent data entry formats
* ✅ Handles variations in user-provided information
* ✅ Accommodates different naming conventions
* ✅ Supports legacy data with formatting inconsistencies
### 3. **Administrative Efficiency**
* ✅ Enables quick user discovery in large datasets
* ✅ Reduces support tickets from failed user lookups
* ✅ Improves admin interface usability
* ✅ Supports bulk operations with approximate matching
## How Fuzzy Search Works
Databunker Pro's fuzzy search implementation uses advanced algorithms to find users based on similarity rather than exact matches. The system analyzes multiple user attributes and returns results ranked by relevance.
### Supported Search Modes
| Search Mode | Description | Use Case |
| ----------- | ------------------------- | ------------------------------------ |
| `login` | Searches user login names | Finding users by username variations |
| `email` | Searches email addresses | Locating users with email typos |
| `phone` | Searches phone numbers | Finding users with phone variations |
| `custom` | Searches by custom index | Funding users with custom variations |
## API Usage
### Prerequisites
Before performing fuzzy searches, you need to:
1. **Create a Bulk List Unlock**: Required for security and audit purposes
2. **Obtain proper permissions**: Ensure your token has search capabilities
3. **Prepare search parameters**: Define search mode and criteria
### Basic Fuzzy Search Request
```bash theme={null}
curl -X POST "https://your-databunker-instance/v2/UserSearch" \
-H "Content-Type: application/json" \
-H "X-Bunker-Token: YOUR_ACCESS_TOKEN" \
-d '{
"mode": "login",
"identity": "user0",
"unlockuuid": "your-unlock-uuid"
}'
```
### JavaScript/TypeScript Example (Using Official SDK)
```javascript theme={null}
// ES Modules
import DatabunkerproAPI from "databunkerpro-js";
// CommonJS
// const DatabunkerproAPI = require('databunkerpro-js');
// Initialize the client
const client = new DatabunkerproAPI(
"https://your-databunker-instance.com",
"your-token"
);
// Step 1: Create bulk list unlock
const unlockResponse = await client.bulkListUnlock();
const unlockUUID = unlockResponse.unlockuuid;
// Step 2: Perform fuzzy search
const searchResponse = await client.userSearch({
mode: "login",
identity: "user0",
unlockuuid: unlockUUID,
});
// Process results
if (searchResponse.status === "ok") {
const users = searchResponse.rows;
console.log(`Found ${users.length} matching users`);
users.forEach((user) => {
const profile = user.profile;
console.log(`User: ${profile.login} - ${profile.email}`);
});
}
```
### Python Example (Using Official SDK)
```python theme={null}
from databunkerpro import DatabunkerproAPI
# Initialize the client
api = DatabunkerproAPI(
base_url="https://your-databunker-instance",
x_bunker_token="YOUR_ACCESS_TOKEN",
x_bunker_tenant="your-tenant-name" # Optional for multi-tenant setups
)
# Step 1: Create bulk list unlock
unlock_response = api.bulk_list_unlock()
unlock_uuid = unlock_response["unlockuuid"]
# Step 2: Perform fuzzy search
search_response = api.user_search(
mode="login",
identity="user0",
unlockuuid=unlock_uuid
)
if search_response["status"] == "ok":
users = search_response["rows"]
print(f"Found {len(users)} matching users")
for user in users:
profile = user["profile"]
print(f"User: {profile['login']} - {profile['email']}")
```
## Real-World Use Cases
### 1. **Customer Support**
When customers contact support with partial or misspelled information, fuzzy search helps quickly locate their accounts:
### 2. **User Administration**
Administrators can find users even with incomplete information:
### 3. **Data Migration**
During system migrations, fuzzy search helps match records with slight variations:
## Security Considerations
### Access Control
Fuzzy search respects Databunker Pro's Conditional Role-Based Access Control (CRBAC):
* **Policy Enforcement**: Search results are filtered based on user permissions
* **Audit Logging**: All search operations are logged for compliance
* **Data Minimization**: Only authorized fields are returned in results
### Privacy Protection
* **Encrypted Storage**: All user data remains encrypted during search operations
* **Secure Transmission**: Search requests use HTTPS encryption
* **Access Logging**: Complete audit trail of all search activities
## Error Handling
### Common Error Scenarios
```javascript theme={null}
try {
const searchResponse = await api.makeRequest("UserSearch", {
mode: "login",
identity: "nonexistent",
unlockuuid: unlockUUID,
});
if (searchResponse.status === "error") {
console.log("Search failed:", searchResponse.message);
} else if (searchResponse.rows.length === 0) {
console.log("No matching users found");
}
} catch (error) {
console.error("Search request failed:", error);
}
```
## Official JavaScript/TypeScript SDK
For JavaScript and TypeScript developers, we provide an official SDK that simplifies integration with Databunker Pro's fuzzy search capabilities.
### Installation
```bash theme={null}
npm install databunkerpro-js
```
### SDK Features
The [Databunker Pro JavaScript client](https://github.com/securitybunker/databunkerpro-js) provides:
* **TypeScript support** with full type definitions
* **ES Modules and CommonJS** compatibility
* **Comprehensive API coverage** for all Databunker Pro features
* **Built-in error handling** and validation
* **User Management** (create, read, update, delete)
* **Token Management**
* **Fuzzy Search capabilities**
* **System Operations**
### Advanced JavaScript/TypeScript Example
```typescript theme={null}
import DatabunkerproAPI from "databunkerpro-js";
class UserSearchService {
private client: DatabunkerproAPI;
private unlockUUID?: string;
constructor(baseUrl: string, token: string) {
this.client = new DatabunkerproAPI(baseUrl, token);
}
private async ensureUnlock(): Promise {
if (!this.unlockUUID) {
const response = await this.client.bulkListUnlock();
this.unlockUUID = response.unlockuuid;
}
return this.unlockUUID;
}
async searchUsers(mode: string, identity: string) {
const unlockUUID = await this.ensureUnlock();
const response = await this.client.userSearch({
mode,
identity,
unlockuuid: unlockUUID,
});
if (response.status !== "ok") {
throw new Error(`Search failed: ${response.message || "Unknown error"}`);
}
return response.rows;
}
async findUserByEmail(email: string) {
return this.searchUsers("email", email);
}
async findUserByLogin(login: string) {
return this.searchUsers("login", login);
}
async findUserByPhone(phone: string) {
return this.searchUsers("phone", phone);
}
}
// Usage example
const searchService = new UserSearchService(
"https://your-databunker-instance.com",
"your-token"
);
// Search for users with error handling
try {
const users = await searchService.findUserByLogin("john");
console.log(`Found ${users.length} matching users`);
users.forEach((user) => {
const profile = user.profile;
console.log(`Found: ${profile.login} - ${profile.email}`);
});
} catch (error) {
console.error("Search failed:", error.message);
}
```
## Official Python SDK
For Python developers, we provide an official SDK that simplifies integration with Databunker Pro's fuzzy search capabilities.
### Installation
```bash theme={null}
pip install databunkerpro
```
Or install directly from GitHub:
```bash theme={null}
pip install git+https://github.com/securitybunker/databunkerpro-python.git
```
### SDK Features
The [Databunker Pro Python client](https://github.com/securitybunker/databunkerpro-python) provides:
* **Type hints and comprehensive documentation**
* **Error handling and validation**
* **User Management** (create, read, update, delete)
* **Token Management**
* **Fuzzy Search capabilities**
* **System Statistics**
### Advanced Python Example
```python theme={null}
from databunkerpro import DatabunkerproAPI
from typing import List, Dict, Optional
class UserSearchService:
def __init__(self, base_url: str, token: str, tenant: Optional[str] = None):
self.api = DatabunkerproAPI(
base_url=base_url,
x_bunker_token=token,
x_bunker_tenant=tenant
)
self._unlock_uuid: Optional[str] = None
def _ensure_unlock(self) -> str:
"""Ensure we have a valid unlock UUID"""
if not self._unlock_uuid:
response = self.api.bulk_list_unlock()
self._unlock_uuid = response["unlockuuid"]
return self._unlock_uuid
def search_users(self, mode: str, identity: str) -> List[Dict]:
"""Search for users using fuzzy matching"""
unlock_uuid = self._ensure_unlock()
response = self.api.user_search(
mode=mode,
identity=identity,
unlockuuid=unlock_uuid
)
if response["status"] == "ok":
return response["rows"]
else:
raise Exception(f"Search failed: {response.get('message', 'Unknown error')}")
def find_user_by_email(self, email: str) -> List[Dict]:
"""Find users by email with fuzzy matching"""
return self.search_users("email", email)
def find_user_by_login(self, login: str) -> List[Dict]:
"""Find users by login with fuzzy matching"""
return self.search_users("login", login)
# Usage example
search_service = UserSearchService(
base_url="https://your-databunker-instance",
token="YOUR_ACCESS_TOKEN",
tenant="your-tenant-name"
)
# Search for users
users = search_service.find_user_by_login("john")
for user in users:
profile = user["profile"]
print(f"Found: {profile['login']} - {profile['email']}")
```
## Integration Examples
The JavaScript/TypeScript examples above can be easily adapted for any frontend framework (React, Vue, Angular) or backend environment (Node.js, Deno, Bun). The core API integration pattern remains the same across all environments.
## Conclusion
Databunker Pro's Fuzzy Search API provides a powerful, secure, and efficient way to find users in large datasets. By combining intelligent matching algorithms with robust security controls, it enables applications to deliver excellent user experiences while maintaining data privacy and compliance requirements.
The fuzzy search capability is particularly valuable for:
* Customer support systems
* User administration interfaces
* Data migration projects
* Applications with large user bases
### Getting Started
We provide official SDKs for both JavaScript/TypeScript and Python developers:
**For JavaScript/TypeScript developers:**
* [Databunker Pro JavaScript SDK](https://github.com/securitybunker/databunkerpro-js) - `npm install databunkerpro-js`
* TypeScript support with full type definitions
* ES Modules and CommonJS compatibility
* Comprehensive API coverage
**For Python developers:**
* [Databunker Pro Python SDK](https://github.com/securitybunker/databunkerpro-python) - `pip install databunkerpro`
* Type hints and comprehensive documentation
* Built-in error handling and validation
Both SDKs provide:
* Simplified API integration
* Built-in error handling and validation
* Support for all Databunker Pro features including fuzzy search
With proper implementation and security considerations, fuzzy search can significantly improve your application's usability and user satisfaction.
# Record versioning
Source: https://docs.databunker.org/pro/concepts/record-versioning
**Record Versioning** in Databunker Pro provides automatic version history tracking for user profiles and application data. Every time a record is created or updated, Databunker Pro automatically creates a new version, allowing you to track changes over time, audit data modifications, and restore previous states when needed.
## Configuration
Record versioning is **not enabled by default**. To enable versioning, you need to configure it in your `databunker.yaml` configuration file:
```yaml theme={null}
versioning:
enabled: true
max_versions: 10
max_version_retention_period: "1m"
```
After enabling versioning in the configuration file, restart your Databunker Pro instance for the changes to take effect.
## What Problems Does Record Versioning Solve?
### 1. **Change History & Data Integrity**
* ✅ Complete history of all data changes over time
* ✅ Track what changed and when it changed
* ✅ Verify data integrity with cryptographic hashes
* ✅ Maintain immutable record of data evolution
### 2. **Data Recovery & Rollback**
* ✅ Restore previous versions of user data
* ✅ Recover from accidental data modifications
* ✅ Undo unwanted changes quickly
* ✅ Maintain data consistency across systems
### 3. **Change Tracking & Analysis**
* ✅ Understand how user data evolves over time
* ✅ Analyze patterns in data modifications
* ✅ Identify data quality issues
* ✅ Support forensic investigations
## How Record Versioning Works
Databunker Pro automatically creates a new version every time you:
* Create a new user record
* Update a user profile
* Create application data
* Update application data
Each version includes:
* **Version number**: Sequential integer starting from 1
* **Operation time**: Unix timestamp of when the version was created
* **MD5 hash**: Cryptographic hash for integrity verification
* **Full record data**: Complete snapshot of the record at that point in time
## Supported Record Types
Record versioning is available for:
| Record Type | API Endpoints | Use Case |
| -------------------- | -------------------------------------------------- | --------------------------------------------------------------- |
| **User Profiles** | `UserListVersions`, `UserGet` (with version) | Track user profile changes, email updates, phone number changes |
| **Application Data** | `AppdataListVersions`, `AppdataGet` (with version) | Track application-specific data changes, configuration updates |
## User Profile Versioning
### Listing User Versions
To see all versions of a user's profile:
```bash theme={null}
curl -X POST "https://your-databunker-instance/v2/UserListVersions" \
-H "Content-Type: application/json" \
-H "X-Bunker-Token: YOUR_ACCESS_TOKEN" \
-d '{
"mode": "token",
"identity": "user-token-here"
}'
```
**Response:**
```json theme={null}
{
"status": "ok",
"versions": [
{
"version": 1,
"optime": 1699123456,
"md5": "a1b2c3d4e5f6..."
},
{
"version": 2,
"optime": 1699123500,
"md5": "b2c3d4e5f6a1..."
},
{
"version": 3,
"optime": 1699123600,
"md5": "c3d4e5f6a1b2..."
}
]
}
```
### Retrieving a Specific User Version
To retrieve a specific version of a user's profile:
```bash theme={null}
curl -X POST "https://your-databunker-instance/v2/UserGet" \
-H "Content-Type: application/json" \
-H "X-Bunker-Token: YOUR_ACCESS_TOKEN" \
-d '{
"mode": "token",
"identity": "user-token-here",
"version": 1
}'
```
**Response:**
```json theme={null}
{
"status": "ok",
"token": "user-token-here",
"profile": {
"login": "versionuser",
"email": "versionuser@email.com"
},
"version": 1
}
```
### JavaScript/TypeScript Example
```javascript theme={null}
import DatabunkerproAPI from "databunkerpro-js";
const client = new DatabunkerproAPI(
"https://your-databunker-instance.com",
"your-token"
);
// Step 1: Create a user
const createResponse = await client.userCreate({
profile: {
login: "versionuser",
email: "versionuser@email.com"
}
});
const userToken = createResponse.token;
// Step 2: Update the user profile
await client.userUpdate({
mode: "token",
identity: userToken,
profile: {
login: "versionuser",
email: "versionuser2@email.com"
}
});
// Step 3: Update again
await client.userUpdate({
mode: "token",
identity: userToken,
profile: {
login: "versionuser",
email: "versionuser3@email.com"
}
});
// Step 4: List all versions
const versionsResponse = await client.userListVersions({
mode: "token",
identity: userToken
});
console.log("User versions:", versionsResponse.versions);
// Output: [
// { version: 1, optime: 1699123456, md5: "..." },
// { version: 2, optime: 1699123500, md5: "..." },
// { version: 3, optime: 1699123600, md5: "..." }
// ]
// Step 5: Retrieve a specific version
const version1 = await client.userGet({
mode: "token",
identity: userToken,
version: 1
});
console.log("Version 1 email:", version1.profile.email);
// Output: "versionuser@email.com"
const version2 = await client.userGet({
mode: "token",
identity: userToken,
version: 2
});
console.log("Version 2 email:", version2.profile.email);
// Output: "versionuser2@email.com"
```
### Python Example
```python theme={null}
from databunkerpro import DatabunkerproAPI
api = DatabunkerproAPI(
base_url="https://your-databunker-instance",
x_bunker_token="YOUR_ACCESS_TOKEN"
)
# Step 1: Create a user
create_response = api.user_create({
"profile": {
"login": "versionuser",
"email": "versionuser@email.com"
}
})
user_token = create_response["token"]
# Step 2: Update the user profile
api.user_update({
"mode": "token",
"identity": user_token,
"profile": {
"login": "versionuser",
"email": "versionuser2@email.com"
}
})
# Step 3: Update again
api.user_update({
"mode": "token",
"identity": user_token,
"profile": {
"login": "versionuser",
"email": "versionuser3@email.com"
}
})
# Step 4: List all versions
versions_response = api.user_list_versions({
"mode": "token",
"identity": user_token
})
print("User versions:", versions_response["versions"])
# Output: [
# {"version": 1, "optime": 1699123456, "md5": "..."},
# {"version": 2, "optime": 1699123500, "md5": "..."},
# {"version": 3, "optime": 1699123600, "md5": "..."}
# ]
# Step 5: Retrieve a specific version
version1 = api.user_get({
"mode": "token",
"identity": user_token,
"version": 1
})
print("Version 1 email:", version1["profile"]["email"])
# Output: "versionuser@email.com"
version2 = api.user_get({
"mode": "token",
"identity": user_token,
"version": 2
})
print("Version 2 email:", version2["profile"]["email"])
# Output: "versionuser2@email.com"
```
## Application Data Versioning
Application data versioning works similarly to user profile versioning, but tracks changes to application-specific data associated with users.
### Listing Appdata Versions
```bash theme={null}
curl -X POST "https://your-databunker-instance/v2/AppdataListVersions" \
-H "Content-Type: application/json" \
-H "X-Bunker-Token: YOUR_ACCESS_TOKEN" \
-d '{
"mode": "token",
"identity": "user-token-here",
"appname": "mytestapp"
}'
```
**Response:**
```json theme={null}
{
"status": "ok",
"versions": [
{
"version": 1,
"optime": 1699123456,
"md5": "a1b2c3d4e5f6..."
},
{
"version": 2,
"optime": 1699123500,
"md5": "b2c3d4e5f6a1..."
},
{
"version": 3,
"optime": 1699123600,
"md5": "c3d4e5f6a1b2..."
}
]
}
```
### Retrieving a Specific Appdata Version
```bash theme={null}
curl -X POST "https://your-databunker-instance/v2/AppdataGet" \
-H "Content-Type: application/json" \
-H "X-Bunker-Token: YOUR_ACCESS_TOKEN" \
-d '{
"mode": "token",
"identity": "user-token-here",
"appname": "mytestapp",
"version": 1
}'
```
### JavaScript/TypeScript Example
```javascript theme={null}
import DatabunkerproAPI from "databunkerpro-js";
const client = new DatabunkerproAPI(
"https://your-databunker-instance.com",
"your-token"
);
// Step 1: Create user
const userResponse = await client.userCreate({
profile: {
login: "appuser0",
email: "appuser0@email.com"
}
});
const userToken = userResponse.token;
// Step 2: Create appdata
await client.appdataCreate({
appname: "mytestapp",
mode: "token",
identity: userToken,
appdata: {
score: 0,
note: "init"
}
});
// Step 3: Update appdata multiple times
for (let v = 1; v <= 3; v++) {
await client.appdataUpdate({
appname: "mytestapp",
mode: "token",
identity: userToken,
appdata: {
score: v,
note: `update${v}`
}
});
}
// Step 4: List all appdata versions
const versionsResponse = await client.appdataListVersions({
appname: "mytestapp",
mode: "token",
identity: userToken
});
console.log("Appdata versions:", versionsResponse.versions);
// Output: [
// { version: 1, optime: 1699123456, md5: "..." },
// { version: 2, optime: 1699123500, md5: "..." },
// { version: 3, optime: 1699123600, md5: "..." },
// { version: 4, optime: 1699123700, md5: "..." }
// ]
// Step 5: Retrieve a specific version
const version1 = await client.appdataGet({
appname: "mytestapp",
mode: "token",
identity: userToken,
version: 1
});
console.log("Version 1 appdata:", version1.appdata);
// Output: { score: 0, note: "init" }
const version2 = await client.appdataGet({
appname: "mytestapp",
mode: "token",
identity: userToken,
version: 2
});
console.log("Version 2 appdata:", version2.appdata);
// Output: { score: 1, note: "update1" }
```
### Python Example
```python theme={null}
from databunkerpro import DatabunkerproAPI
api = DatabunkerproAPI(
base_url="https://your-databunker-instance",
x_bunker_token="YOUR_ACCESS_TOKEN"
)
# Step 1: Create user
user_response = api.user_create({
"profile": {
"login": "appuser0",
"email": "appuser0@email.com"
}
})
user_token = user_response["token"]
# Step 2: Create appdata
api.appdata_create({
"appname": "mytestapp",
"mode": "token",
"identity": user_token,
"appdata": {
"score": 0,
"note": "init"
}
})
# Step 3: Update appdata multiple times
for v in range(1, 4):
api.appdata_update({
"appname": "mytestapp",
"mode": "token",
"identity": user_token,
"appdata": {
"score": v,
"note": f"update{v}"
}
})
# Step 4: List all appdata versions
versions_response = api.appdata_list_versions({
"appname": "mytestapp",
"mode": "token",
"identity": user_token
})
print("Appdata versions:", versions_response["versions"])
# Step 5: Retrieve a specific version
version1 = api.appdata_get({
"appname": "mytestapp",
"mode": "token",
"identity": user_token,
"version": 1
})
print("Version 1 appdata:", version1["appdata"])
# Output: {"score": 0, "note": "init"}
version2 = api.appdata_get({
"appname": "mytestapp",
"mode": "token",
"identity": user_token,
"version": 2
})
print("Version 2 appdata:", version2["appdata"])
# Output: {"score": 1, "note": "update1"}
```
## Real-World Use Cases
### 1. **Compliance & Audit Requirements**
Many regulations require maintaining a complete history of data changes:
```javascript theme={null}
// Track all changes to user email for GDPR compliance
const versions = await client.userListVersions({
mode: "token",
identity: userToken
});
// Generate audit report
const auditReport = versions.versions.map(v => ({
version: v.version,
timestamp: new Date(v.optime * 1000),
hash: v.md5
}));
```
### 2. **Data Recovery**
Restore previous versions when data is accidentally modified:
```javascript theme={null}
// User's email was accidentally changed
// Restore from version 2
const previousVersion = await client.userGet({
mode: "token",
identity: userToken,
version: 2
});
// Restore the email
await client.userUpdate({
mode: "token",
identity: userToken,
profile: {
email: previousVersion.profile.email
}
});
```
### 3. **Change Analysis**
Analyze how user data changes over time:
```javascript theme={null}
// Get all versions and compare changes
const versions = await client.userListVersions({
mode: "token",
identity: userToken
});
for (const v of versions.versions) {
const record = await client.userGet({
mode: "token",
identity: userToken,
version: v.version
});
console.log(`Version ${v.version}:`, {
timestamp: new Date(v.optime * 1000),
email: record.profile.email
});
}
```
### 4. **Application State Management**
Track changes to application-specific data:
```javascript theme={null}
// Track score changes in a game application
const versions = await client.appdataListVersions({
appname: "gameapp",
mode: "token",
identity: userToken
});
// Find when score reached certain milestones
for (const v of versions.versions) {
const appdata = await client.appdataGet({
appname: "gameapp",
mode: "token",
identity: userToken,
version: v.version
});
if (appdata.appdata.score >= 1000) {
console.log(`Score milestone reached at version ${v.version}`);
}
}
```
## Security Considerations
### Access Control
Record versioning respects Databunker Pro's Conditional Role-Based Access Control (CRBAC):
* **Policy Enforcement**: Access to version history is controlled by policies
* **Audit Logging**: All version access operations are logged
### Privacy Protection
* **Encrypted Storage**: All version data remains encrypted at rest
* **Secure Transmission**: Version requests use HTTPS encryption
* **Access Logging**: Complete audit trail of all version access activities
## Version Metadata
Each version includes important metadata:
| Field | Type | Description |
| --------- | ------- | ------------------------------------------------------- |
| `version` | integer | Sequential version number (starts at 1) |
| `optime` | integer | Unix timestamp when the version was created |
| `md5` | string | MD5 hash of the version data for integrity verification |
## Conclusion
Databunker Pro's Record Versioning feature provides a powerful, secure, and efficient way to track changes to user profiles and application data. By automatically maintaining a complete version history with cryptographic integrity verification, it enables applications to:
* Meet compliance and audit requirements
* Recover from accidental data modifications
* Analyze data changes over time
* Maintain data integrity and security
The versioning capability is particularly valuable for:
* Compliance-driven applications (GDPR, HIPAA, etc.)
* Applications requiring audit trails
* Systems with frequent data updates
* Applications needing data recovery capabilities
# Select security
Source: https://docs.databunker.org/pro/concepts/select-security
## Secure bulk retrieval challenge
The primary security challenge with both SQL and NoSQL databases is the risk of secure bulk retrieval (or record-dumping) queries, such as a "SELECT \*" request.
When combined with SQL injection or GraphQL injection vulnerabilities, attackers can exploit these queries to dump entire database in a matter of seconds. A malicious actor can access your sensitive records even if a database encryption solution is implemented.
To address this threat, the original version of Databunker Pro was designed to retrieve user records only when specific user details were provided. This approach significantly limited attackers' ability to enumerate users stored in Databunker. Even if an attacker managed to obtain a Databunker Pro access token, they would still need to provide specific details like the user's email, phone number, or UUID to access any information. From a security perspective, this design was robust and highly effective.
## The Usability Dilemma
Despite the strong security model, we began losing business. Companies provided feedback that they needed a way to list all users as part of their application's admin interface.
Initially, we firmly opposed introducing any API that allowed bulk user retrieval, as it conflicted with our strict security principles.
However, this resistance came at a cost. While our security model remained robust, our product's usability suffered, which negatively impacted our business.
We realized we needed a solution that could balance these conflicting requirements: maintaining high security while providing admins with essential functionality.
## Iteration 1: Adding Basic Controls for Bulk Access
Our initial attempt to balance usability and security introduced a two-step approach:
1. **Configuration Setting:** Admins could enable or disable the ability to dump user records entirely.
2. **POST Request Requirement:** A bulk data dump required a POST request, ensuring the action couldn't be triggered by a simple GET request.
This solution addressed some concerns but still left room for improvement.
## Iteration 2: Secure Unlock Mechanism
Over time, we developed a more secure solution:
1. **Unlock Request:** A special API unlock request must be submited, specifying whether they want to unlock all users or a specific group of users.
2. **Temporary Token:** The unlock request generates a temporary token with a short expiration window (e.g., a few minutes).
3. **Token Validation:** During the token's validity period, user records can only be dumped if the token is included in the API request.
**This solution ensured that bulk data access required explicit admin intent, was time-restricted, and could not be abused by malicious actors.**
The bulk unlock UUID is designed with strict time constraints for enhanced security:
* It expires automatically after a few seconds
* It must be included when retrieving records for any group of users
* A new UUID must be requested for subsequent bulk operations
## Iteration 3: Fine-Grained Access Control with Policy Engine
Our latest iteration introduces a powerful policy engine that provides granular control over bulk operations and user listing capabilities. This enhancement allows organizations to:
1. **Control Bulk Operations Access:** Define exactly who has the right to perform bulk unlock API requests
2. **Group-Specific Access:** Restrict user listing to specific groups or departments
3. **Field-Level Security:** Control which user fields are visible in bulk operations
4. **Role-Based Controls:** Implement role-based access patterns for different admin types
Here's an example policy that demonstrates these capabilities:
```json theme={null}
{
"policyname": "ManagerAccess",
"policy": {
"Effect": "Allow",
"Principal": { "Role": "manager" },
"Action": ["UserGet", "BulkListGroupUsers"],
"Resource": [
"${target_group_members:role/team-member}.profile.name",
"${target_group_members:role/team-member}.profile.phone",
"${target_group_members:role/team-member}.group"
],
"Condition": {
"StringEquals": {
"${user_group_id}": "${target_group_id}"
}
}
}
}
```
This policy demonstrates several key security features:
1. **Limited Actions:** The manager role can only perform specific actions (`UserGet` and `BulkListGroupUsers`)
2. **Field Restrictions:** Access is limited to specific fields (name, phone, group)
3. **Group Isolation:** Managers can only access members of their own group
4. **Automatic Data Masking:** Other sensitive fields are automatically masked
By implementing these policies, organizations can:
* Allow HR managers to list only their department members
* Restrict sensitive field access in bulk operations
* Implement hierarchical access patterns
* Maintain audit trails of all bulk access operations
This policy-based approach provides the flexibility needed for complex organizational structures while maintaining strict security controls. It represents a significant evolution from our previous iterations, offering both the security we're known for and the granular control our customers need.
## Conclusion
By evolving our approach from basic controls to a secure unlock mechanism, we successfully balanced security and usability. The unlock-and-token method allowed us to meet customer requirements for admin functionality while maintaining the strong security principles that Databunker Pro is known for.
This iterative process highlights how addressing user feedback and evolving product features can strengthen both usability and trust without compromising security.
# Sub-accounts
Source: https://docs.databunker.org/pro/concepts/sub-accounts
**Sub-accounts** (also referred to as **hierarchical accounts**) in Databunker Pro enable organizations to create isolated account structures within their Databunker Pro instance. This feature is essential for businesses that need to manage multiple independent accounts, departments, or organizational units while maintaining data isolation and administrative control.
## What Problems Do Sub-accounts Solve?
### 1. **Organizational Structure Management**
* ✅ Create isolated account spaces for different departments or business units
* ✅ Maintain separate administrative control for each sub-account
* ✅ Enable independent data management per sub-account
* ✅ Support hierarchical organizational structures
### 2. **Multi-tenant SaaS Applications**
* ✅ Provide isolated data storage for each customer
* ✅ Enable customer-specific administrative access
* ✅ Maintain complete data separation between accounts
* ✅ Support white-label or reseller scenarios
### 3. **Compliance and Data Isolation**
* ✅ Ensure complete data isolation between sub-accounts
* ✅ Meet regulatory requirements for data separation
* ✅ Enable independent audit trails per sub-account
* ✅ Support compliance with data residency requirements
## Implementation Approaches
Databunker Pro provides two primary approaches for implementing sub-accounts:
1. **Multi-tenancy Support** - Creates isolated tenants with dedicated admin tokens
2. **Groups with Roles and Policies** - Uses Databunker Pro's CRBAC system for group-based management
These approaches can also be combined together to create an even more flexible solution that leverages both database-level isolation from multi-tenancy and fine-grained access control from groups.
## Approach 1: Multi-tenancy Support
Multi-tenancy is the recommended approach when you need complete data isolation and independent administrative control for each sub-account. After creating a tenant, you receive a tenant admin token that allows full management of all records within that tenant.
### How It Works
When you create a new tenant using the multi-tenancy feature:
1. A new isolated tenant is created with its own data namespace
2. A **tenant admin token** is generated that provides full administrative access
3. All records created within this tenant are completely isolated from other tenants at the database level using PostgreSQL's row-level security (RLS). **Note:** Multi-tenancy requires PostgreSQL and is not supported with MySQL.
4. The tenant admin token can manage all user records, application data, and configurations within the tenant
Records are separated from one tenant to another at the database level. This separation is implemented using PostgreSQL's row-level security mechanism, which ensures that queries executed by specific tenants are restricted to their own records, providing complete data isolation.
### Creating a Sub-account with Multi-tenancy
```bash theme={null}
curl -H 'X-Bunker-Token: ROOT-ACCESS-TOKEN' \
-X POST https://your-databunker-instance/v2/TenantCreate \
-H 'Content-Type: application/json' \
--data '{
"tenantorg": "acme-corp",
"tenantname": "subaccount-001"
}'
```
**Response:**
```json theme={null}
{
"status": "ok",
"xtoken": "TENANT-ADMIN-TOKEN-001"
}
```
### Using the Tenant Admin Token
Once you have the tenant admin token, you can use it to manage all records within that tenant:
```bash theme={null}
# Create a user in the sub-account
curl -H 'X-Bunker-Token: TENANT-ADMIN-TOKEN-001' \
-H 'X-Bunker-Tenant: subaccount-001' \
-H 'Content-Type: application/json' \
-X POST https://your-databunker-instance/v2/UserCreate \
--data '{
"profile": {
"login": "user1",
"email": "user1@subaccount-001.com",
"firstname": "John",
"lastname": "Doe"
}
}'
```
### JavaScript/TypeScript Example
```javascript theme={null}
import DatabunkerproAPI from "databunkerpro-js";
// Initialize root admin client
const rootClient = new DatabunkerproAPI(
"https://your-databunker-instance.com",
"ROOT-ACCESS-TOKEN"
);
// Step 1: Create a new sub-account (tenant)
const tenantResponse = await rootClient.tenantCreate({
tenantorg: "acme-corp",
tenantname: "subaccount-001"
});
const tenantAdminToken = tenantResponse.xtoken;
const tenantName = "subaccount-001";
// Step 2: Initialize client with tenant admin token
const tenantClient = new DatabunkerproAPI(
"https://your-databunker-instance.com",
tenantAdminToken
);
// Step 3: Create users in the sub-account
const userResponse = await tenantClient.userCreate({
profile: {
login: "user1",
email: "user1@subaccount-001.com",
firstname: "John",
lastname: "Doe"
}
});
console.log("Sub-account created with tenant admin token:", tenantAdminToken);
console.log("User created in sub-account:", userResponse.token);
```
### Python Example
```python theme={null}
from databunkerpro import DatabunkerproAPI
# Initialize root admin client
root_api = DatabunkerproAPI(
base_url="https://your-databunker-instance",
x_bunker_token="ROOT-ACCESS-TOKEN"
)
# Step 1: Create a new sub-account (tenant)
tenant_response = root_api.tenant_create({
"tenantorg": "acme-corp",
"tenantname": "subaccount-001"
})
tenant_admin_token = tenant_response["xtoken"]
tenant_name = "subaccount-001"
# Step 2: Initialize client with tenant admin token
tenant_api = DatabunkerproAPI(
base_url="https://your-databunker-instance",
x_bunker_token=tenant_admin_token,
x_bunker_tenant=tenant_name
)
# Step 3: Create users in the sub-account
user_response = tenant_api.user_create({
"profile": {
"login": "user1",
"email": "user1@subaccount-001.com",
"firstname": "John",
"lastname": "Doe"
}
})
print(f"Sub-account created with tenant admin token: {tenant_admin_token}")
print(f"User created in sub-account: {user_response['token']}")
```
### Benefits of Multi-tenancy Approach
* **Complete Data Isolation**: Each tenant has its own isolated data namespace
* **Independent Administration**: Tenant admin tokens provide full control within the tenant
* **Scalability**: Supports unlimited tenants with PostgreSQL row-level security (requires PostgreSQL, not available with MySQL)
* **Security**: Built-in tenant separation at the database level
* **Compliance**: Meets data residency and isolation requirements
## Approach 2: Groups with Roles and Policies
The groups approach leverages Databunker Pro's Conditional Role-Based Access Control (CRBAC) system. Each group can store sub-accounts, and a group admin user manages all users within that group. This approach is implemented using roles and policies.
### How It Works
With the groups approach:
1. Create a group to represent the sub-account
2. Assign a **group admin** role to a user who will manage the sub-account
3. Create policies that grant the group admin access to manage users within the group
4. Add users to the group as needed
5. The group admin can manage all users within their assigned group
### Creating a Sub-account with Groups
```bash theme={null}
# Step 1: Create a group admin user
curl -H 'X-Bunker-Token: YOUR-ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-X POST https://your-databunker-instance/v2/UserCreate \
--data '{
"profile": {
"login": "group-admin-001",
"email": "admin@subaccount-001.com",
"firstname": "Admin",
"lastname": "User"
}
}'
# Step 2: Create a group for the sub-account
curl -H 'X-Bunker-Token: YOUR-ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-X POST https://your-databunker-instance/v2/GroupCreate \
--data '{
"groupname": "subaccount-001",
"description": "Sub-account group 001"
}'
# Step 3: Add the group admin to the group with admin role
curl -H 'X-Bunker-Token: YOUR-ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-X POST https://your-databunker-instance/v2/GroupAddUser \
--data '{
"groupname": "subaccount-001",
"mode": "token",
"identity": "USER-TOKEN-FROM-STEP-1",
"role": "group-admin"
}'
```
### Creating Policies for Group Admin
Create a policy that allows the group admin to manage all users within their group:
```bash theme={null}
curl -H 'X-Bunker-Token: YOUR-ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-X POST https://your-databunker-instance/v2/PolicyCreate \
--data '{
"policyname": "subaccount-admin-policy",
"policy": {
"Effect": "Allow",
"Principal": { "Role": "group-admin" },
"Action": [
"UserGet",
"UserCreate",
"UserUpdate",
"UserDelete",
"BulkListGroupUsers",
"BulkListUnlock",
"GroupListUserGroups"
],
"Resource": [
"${target_group_members}.profile",
"${target_group_members}.consent",
"${target_group_members}.appdata"
],
"Condition": {
"StringEquals": {
"${principal_group_id}": "${target_group_id}"
}
}
}
}'
```
### JavaScript/TypeScript Example
```javascript theme={null}
import DatabunkerproAPI from "databunkerpro-js";
const client = new DatabunkerproAPI(
"https://your-databunker-instance.com",
"YOUR-ACCESS-TOKEN"
);
// Step 1: Create a group admin user
const adminResponse = await client.userCreate({
profile: {
login: "group-admin-001",
email: "admin@subaccount-001.com",
firstname: "Admin",
lastname: "User"
}
});
const adminToken = adminResponse.token;
// Step 2: Create a group for the sub-account
await client.groupCreate({
groupname: "subaccount-001",
description: "Sub-account group 001"
});
// Step 3: Add the group admin to the group with admin role
await client.groupAddUser({
groupname: "subaccount-001",
mode: "token",
identity: adminToken,
role: "group-admin"
});
// Step 4: Create policy for group admin
await client.policyCreate({
policyname: "subaccount-admin-policy",
policy: {
Effect: "Allow",
Principal: { Role: "group-admin" },
Action: [
"UserGet",
"UserCreate",
"UserUpdate",
"UserDelete",
"BulkListGroupUsers",
"BulkListUnlock",
"GroupListUserGroups"
],
Resource: [
"${target_group_members}.profile",
"${target_group_members}.consent",
"${target_group_members}.appdata"
],
Condition: {
StringEquals: {
"${principal_group_id}": "${target_group_id}"
}
}
}
});
// Step 5: Group admin can now create users in their group
const groupAdminClient = new DatabunkerproAPI(
"https://your-databunker-instance.com",
adminToken
);
// Create a user in the sub-account
const userResponse = await groupAdminClient.userCreate({
profile: {
login: "user1",
email: "user1@subaccount-001.com",
firstname: "John",
lastname: "Doe"
}
});
// Add user to the group
await groupAdminClient.groupAddUser({
groupname: "subaccount-001",
mode: "token",
identity: userResponse.token,
role: "member"
});
console.log("Sub-account created using groups approach");
console.log("Group admin token:", adminToken);
```
### Benefits of Groups Approach
* **Flexible Access Control**: Fine-grained permissions using CRBAC policies
* **Role-Based Management**: Different roles can be assigned within groups
* **Conditional Access**: Policies can include complex conditions for access control
* **Compliance Support**: Supports FERPA, GDPR, and DPDPA compliance scenarios
* **Hierarchical Structures**: Supports parent-child relationships within groups
## Choosing the Right Approach
### Use Multi-tenancy When:
* You need **complete data isolation** between sub-accounts
* Each sub-account requires **independent administrative control**
* You're building a **multi-tenant SaaS application**
* You need to meet **strict data residency requirements**
* You want **database-level isolation** for security (requires PostgreSQL, not available with MySQL)
### Use Groups Approach When:
* You need **flexible, role-based access control** within sub-accounts
* You want to implement **hierarchical organizational structures**
* You need **conditional access policies** (e.g., parent-child relationships)
* You're building **compliance-focused applications** (FERPA, GDPR, DPDPA)
* You want **fine-grained permissions** for different user roles
## Real-World Use Cases
### 1. **SaaS Multi-tenant Application**
Create isolated sub-accounts for each customer:
```javascript theme={null}
// Create a tenant for each customer
const customerTenant = await rootClient.tenantCreate({
tenantorg: "saas-provider",
tenantname: `customer-${customerId}`
});
// Provide customer with their tenant admin token
// Customer can now manage their own data independently
```
### 2. **Departmental Sub-accounts**
Organize departments within an organization:
```javascript theme={null}
// Create a group for each department
await client.groupCreate({
groupname: "engineering-department",
description: "Engineering team sub-account"
});
// Assign department admin
await client.groupAddUser({
groupname: "engineering-department",
mode: "token",
identity: deptAdminToken,
role: "group-admin"
});
```
### 3. **Reseller/Partner Program**
Enable partners to manage their own customer data:
```javascript theme={null}
// Create tenant for each reseller
const resellerTenant = await rootClient.tenantCreate({
tenantorg: "partner-program",
tenantname: `reseller-${resellerId}`
});
// Reseller gets tenant admin token to manage their customers
```
## Security Considerations
### Multi-tenancy Security
* **Row-Level Security**: PostgreSQL RLS ensures tenant data isolation (requires PostgreSQL, not available with MySQL)
* **Token-Based Access**: Tenant admin tokens are scoped to their tenant
* **Audit Logging**: All tenant operations are logged separately
* **Encryption**: Each tenant's data is encrypted independently
### Groups Security
* **Policy Enforcement**: CRBAC policies control all access
* **Role Validation**: Roles are verified before granting access
* **Condition Checks**: Policies include conditions for additional security
* **Audit Trail**: All group operations are logged with role information
## Best Practices
1. **Token Management**: Securely store and rotate tenant admin tokens
2. **Policy Design**: Design policies carefully to ensure proper access control
3. **Regular Audits**: Review sub-account access and permissions regularly
4. **Monitoring**: Monitor sub-account activity for security and compliance
5. **Documentation**: Document which approach is used for each sub-account
## Conclusion
Databunker Pro provides two powerful approaches for implementing sub-accounts:
* **Multi-tenancy** offers complete isolation and independent administration
* **Groups with CRBAC** provides flexible, role-based access control
Both approaches enable organizations to create secure, scalable sub-account structures that meet their specific requirements for data isolation, administrative control, and compliance.
**The approaches can be combined together** to create an even more flexible solution that leverages database-level isolation from multi-tenancy and fine-grained access control from groups.
Choose the approach that best fits your use case:
* Use **multi-tenancy** for complete isolation and independent administration
* Use **groups** for flexible role-based access control and hierarchical structures
* **Combine both approaches** for maximum flexibility with database-level isolation and fine-grained permissions
# Format-preserving tokenization
Source: https://docs.databunker.org/pro/concepts/tokenization
Databunker Pro features two tokenization engines. The original open-source version supported only tokenization for PII, PHI, and KYC records. The professional version adds a new secure format-preserving tokenization engine.
For instance, Databunker Pro can now tokenize credit card numbers. Unlike other solutions on the market, Databunker Pro was built with the latest data privacy requirements in mind, such as data minimization.
The product was built to handle millions of data tokenization requests, and the Databunker Pro API has been extended to support bulk tokenization requests.
## What Problems Does It Solve?
1. **Data Privacy & Compliance**
* ✅ Meets GDPR data minimization requirements
* ✅ Protects sensitive data while maintaining format
* ✅ Ensures regulatory compliance without sacrificing functionality
* ✅ Reduces scope of PCI DSS compliance
2. **Enterprise Scalability**
* ✅ Handles millions of records through data partitioning
* ✅ Provides high-performance tokenization operations
* ✅ Supports multiple data formats and types
* ✅ Enables efficient data processing at scale
3. **Format Compatibility**
* ✅ Preserves data format for legacy system compatibility
* ✅ Maintains data validation rules (e.g., Luhn algorithm for credit cards)
* ✅ Enables analytics while protecting actual data
* ✅ Supports seamless integration with existing workflows
## 🔄 Supported Data Types
| Original Record Type | Format Preservation | Generated Token Format |
| --------------------- | ------------------- | ------------------------------- |
| Credit Card Number | ✅ (with Luhn check) | Format-preserving or UUID token |
| Uint64/Uint32 integer | ✅ | Format-preserving or UUID token |
| Unix timestamp record | ✅ | Format-preserving or UUID token |
| Text string | ❌ | UUID token |
## 🛠️ Key Features
Databunker Pro has a number of unique features:
### Automatic Expiration
In Databunker Pro, expiration allows you to set a lifespan for sensitive data tokens, ensuring they automatically expire after a defined period.
```json theme={null}
// Set expiration for tokenized records
{
"record": "4532015112830366",
"expiration": "30d" // 30 days
}
```
### Unique Record Support
This unique flag is used for data deduplication. It ensures that each record is saved only once, and the same token value is returned for identical records. If the original record has an expiration flag set, its expiration countdown will be reset from the beginning.
```json theme={null}
// Same input generates same token when enabled
{
"record": "4532015112830366",
"unique": true
}
```
### Dual Token Generation
By default, Databunker Pro generates two tokens: one in UUID format and another in a format-preserving manner.
```json theme={null}
// Example response for credit card tokenization
{
"status": "ok",
"tokenuuid": "550e8400-e29b-41d4-a716-446655440000",
"tokenbase": "4532015112830366" // Format-preserving token
}
```
## 🚀 Getting Started
```bash theme={null}
# Example API call for tokenization
curl -X POST https://databunker.pro/v2/TokenCreate \
-H "X-Bunker-Token: " \
-H "X-Bunker-Tenant: " \
-d '{
"record": "4532015112830366",
"type": "creditcard",
"expiration": "30d"
"unique": true,
}'
```
Output:
```json theme={null}
{
"status": "ok",
"tokenuuid": "550e8400-e29b-41d4-a716-446655440000",
"tokenbase": "4532015112830366" // Format-preserving token
}
```
## 📈 Benefits
* **Compliance**: Built-in GDPR data minimization
* **Security**: Protected sensitive data storage
* **Compatibility**: Format preservation for legacy systems
* **Scalability**: Enterprise-grade performance
* **Flexibility**: Multiple token format support
# Developer tools
Source: https://docs.databunker.org/pro/developer-tools/overview
## SDKs
# Architecture
Source: https://docs.databunker.org/pro/get-started/architecture
In today’s digital landscape, protecting sensitive customer data isn’t just about compliance—it’s about building trust. Databunker Pro offers a next-generation secure vault for personal data (PII/PHI/KYC), combining robust encryption, tokenization, and privacy management in an enterprise-ready platform.
## Core architecture overview
**Backend storage**
* **PostgreSQL**: Reliable, secure backend for encrypted data storage, with row-level security for true multi-tenant isolation.
* **MySQL**: Secure backend for encrypted data storage. Note: Multi-tenancy is not supported with MySQL.
* **Redis**: Used for encrypted storage of session information for faster, secure access.
**Encryption and key management**
* **Two-layer encryption**: Master encryption key secured by a separate wrapping key.
* **Wrapping key rotation**: Rotate without re-encrypting all stored data.
* **Shamir’s Secret Sharing**: Backup the wrapping key securely across multiple trusted parties.
**Privacy management**
* **DPO portal** for oversight and reporting.
* **Consent management**, **audit trails**, and **data minimization** features built-in.
* **One-click personal data reports** and full processing activity logs for compliance.
**Scalability and deployment**
* **Stateless architecture** for easy horizontal scaling on Kubernetes.
* **High availability** with multi-instance deployment and database failover readiness.
* **Container-based deployment**: Docker, Docker Compose, and Kubernetes templates included.
**Integration**
* Available client libraries for **PHP**, **JavaScript/TypeScript**, **Java**, and **Python** to simplify integration.
* Prebuilt connectors for Salesforce, HubSpot, MailChimp, MySQL, PostgreSQL, Oracle, and SQL Server.
![Architecture diagram]()
## Security architecture deep dive
**Data protection**
* **SSL/TLS encryption** for all API and database communication.
* **AES-256 encryption** at rest for all personal data.
* **Secure hash-based indexing** for searchable fields like email, phone number, and login names.
* **Zero clear-text storage** of sensitive information.
**Access control**
* Fine-grained, token-based API authentication.
* Multi-tenant separation using PostgreSQL Row-Level Security (RLS). Note: Multi-tenancy requires PostgreSQL and is not supported with MySQL.
* Default prevention of bulk data extraction.
**Threat protection**
* SQL injection prevention, API rate limiting, and session hardening.
**Key management**
* Wrapping key rotation and Shamir’s Secret Sharing-based key backups.
***
# Specialized data protection features
## PII / PHI / KYC Data Tokenization / User Table Replacement
Databunker Pro enables secure tokenization for full personal profiles (PII/PHI/KYC):
* Accepts complete user profile JSON objects and generates a single token representing the full profile.
* Builds secure hash-based search indexes automatically for searchable fields (e.g., email, phone number, login names), allowing efficient, privacy-preserving lookups.
* Dynamic token expiration options, supporting both sliding and final expiration modes.
* Tokens can be safely stored and used across internal systems without revealing sensitive information.
## Credit card tokenization
For sensitive payment data, Databunker Pro offers dedicated credit card tokenization capabilities:
* Each credit card is tokenized into a secure, unique identifier.
* Supports **unique token generation** (same card → same token if enabled).
* Dynamic token expiration options, supporting both sliding and final expiration modes
* **Bulk tokenization support**: tokenize multiple credit cards efficiently in a single API request, with per-record expiration and validation.
***
## Real-world applications
Organizations across industries use Databunker Pro to protect critical personal data:
* **Financial Services**: Safeguarding customer PII while maintaining regulatory compliance.
* **Healthcare Providers**: Protecting PHI with HIPAA-aligned security controls.
* **E-commerce Platforms**: Managing customer data with GDPR compliance and strong privacy controls.
* **SaaS Providers**: Implementing true multi-tenant security for user data.
***
## Why Choose Databunker Pro?
Databunker Pro is more than just encryption — it’s a **privacy-by-design** foundation for modern organizations. With its advanced encryption model, built-in privacy controls, scalable architecture, and rich integration ecosystem, Databunker Pro empowers you to protect sensitive data, comply with regulations, and earn customer trust.
# Frequently asked questions
Source: https://docs.databunker.org/pro/get-started/faq
### How does Databunker Pro manage sensitive data tokenization?
* Tokenizes entire user records (e.g., PII, PHI, KYC, PCI data) using UUID tokens or format-preserving tokens for specific data records (e.g., credit cards).
* Encrypts data with AES-256 and stores it in a secure vault.
* Provides access via RESTful APIs with role-based access controls (RBAC).
* Supports multi-tenancy for secure management of multiple clients.
### How is tokenization handled for multi-cloud or hybrid environments?
* Supports multi-cloud and hybrid deployments via Docker Compose, Helm charts, or a cloud-hosted version.
* Uses a stateless architecture for consistency across environments with a centralized secure vault for token mapping.
* Enables multi-tenancy for secure data separation in shared cloud or hybrid setups.
* Offers APIs for seamless integration with cloud-native or on-premises systems.
### Does Databunker Pro implement tokenization for PII, card data, or account information? What approach is used?
* Supports PII, card data (PCI), and account information (KYC).
* Tokenizes entire records with UUIDs or uses format-preserving tokenization for specific records (e.g., credit card numbers).
* Maintains data usability while ensuring security.
### Is there a secure vault for storing token-to-data mappings, or is a deterministic, format-preserving method used without a vault?
* Uses a secure vault to store AES-256-encrypted token-to-data mappings.
* Offers format-preserving tokenization for specific records (for example for credit cards).
* Ensures secure storage and retrieval with isolated vaults for different clients via multi-tenancy.
### Are encryption, secure APIs, and access controls in place during tokenization workflows?
* Encrypts data with AES-256 encryption.
* Uses secure RESTful APIs with RBAC to handle tokenization.
* Supports mutual TLS and certificate pinning for legitimate API access.
* Requires time-based tokens for special handling of bulk requests.
* Defines retrievable fields with a masking policy, masking others.
### What are the authentication, encryption, and access control mechanisms for the token vault?
* **Authentication**: Uses temporary UUID-based access tokens (more secure than JWT, as user identity like email/ID isn’t encoded). Supports passwordless options (e.g., one-time codes via email/SMS) for the optional user portal.
* **Encryption**: Employs AES-256 for data and vault storage with secure indexing for searches.
* **Access Controls**: Restricts vault access with RBAC and a masking policy defining retrievable fields (others masked). Tracks operations with audit trails. Ensures secure data isolation for different clients via multi-tenancy.
### Does the tokenization process align with regulations like RBI, PCI DSS, GDPR, etc.?
* Aligns with RBI, DPDPA, PCI DSS, GDPR, HIPAA, ISO 27001, and SOC2 standards.
* Supports data minimization, user consent management, audit trails, and a User Privacy Portal for data subject rights.
* Meets RBI’s data localization and GDPR’s privacy requirements.
* Provides multi-tenancy for compliance in multi-client environments.
### What is the de-tokenization policy? Is it role-based, audited, and strictly controlled?
* Role-based de-tokenization requiring RBAC permissions.
* Defines retrievable fields with a masking policy, masking others.
* Audits all operations with strict controls for compliance.
* Ensures tenant-specific de-tokenization via multi-tenancy.
### What audit and monitoring capabilities are provided for tokenization activities?
* Provides comprehensive audit trails, logging all tokenization and de-tokenization activities (user, timestamp, data accessed, data before and after change).
* Currently offers no special monitoring capabilities beyond audit logs.
* Segregates audit logs per client via multi-tenancy.
### How is high availability and disaster recovery ensured for the tokenization engine?
* Ensures high availability as a stateless service through containerized deployments (Docker, Helm) with load balancing.
* Supports disaster recovery via database backups (PostgreSQL/MySQL) and replication.
### Is the tokenization system scalable to support large transaction volumes (e.g., millions of transactions per day)? What are the performance benchmarks?
* Scales to handle millions of transactions daily, built in Go.
* Uses time-based tokens for secure handling of bulk requests.
* Ensures low latency and high throughput with a stateless, multi-tenant architecture.
* Supports database partitioning for format-preserving records to enhance scalability and performance.
* Specific benchmark results can be generated based on the number of PII and credit card records.
### How is token uniqueness ensured? Do you use randomization, hashing with salt, or cryptographic mapping?
* Ensures token uniqueness by checking for duplicate records in the database and regenerating UUID tokens if duplicates are found.
* Uses cryptographic mapping for format-preserving tokens with hash-based indexing and salts for deduplication.
* Maintains unique tokens per tenant via multi-tenancy.
### What cryptographic algorithms are used in token generation? Are they NIST-compliant?
* Uses AES-256 for encryption, SHA-256 for secure indexing, and cryptographic UUIDs or format-preserving methods for token generation.
* Aligns with NIST standards for encryption and key management.
* Supports secure multi-tenant environments.
### How are keys managed in the tokenization process? Are they stored in an HSM? What is the key rotation and lifecycle management policy?
* Manages keys securely with a **master key** (never exposed) encrypting sensitive data in the vault using AES-256.
* Protects the master key with a **wrapping key**, storable as a Kubernetes secret or retrievable from AWS Key Vault, HashiCorp Vault, or HSMs (requires custom development).
* Supports **Shamir’s Secret Sharing** for generating wrapping keys, requiring 3 out of 5 key shares to reconstruct.
* Configures key rotation following best practices for lifecycle management.
### What mechanisms prevent token mapping leakage or reverse engineering of the token? Is there protection against brute-force or pattern analysis?
* Prevents leakage and reverse engineering by using tokens (UUID-based or format-preserving) as pointers to AES-256-encrypted data in a secure vault.
* Ensures tokens contain no inherent data, making reverse engineering infeasible without vault access.
* Protects against brute-force or pattern analysis with RBAC, audit logs, and optional mutual TLS.
* Prevents cross-tenant leakage via multi-tenancy.
### How does Databunker Pro handle tokenization for structured and unstructured data? Is it applicable to database fields, documents, or images (e.g., OCR data)?
* Tokenizes structured data (e.g., database fields like PII, or credit cards in PCI).
* For unstructured data (e.g., documents, OCR-extracted data), recommends generating a random password, saving it in the user profile, and using it to encrypt the original file.
### What happens if underlying data is updated after a token is generated and sent to the cloud? Is a new token generated, or is the old token updated?
* Maintains the existing token’s validity, mapping to the updated data in the vault.
* Generates no new token unless a new record is created (checked via deduplication).
* Audits and encrypts updates, ensuring tenant-specific updates via multi-tenancy.
* Databunker Pro team plans to release record versioning in a future version.
# Databunker Pro
Source: https://docs.databunker.org/pro/get-started/overview
Databunker Pro is a self-hosted secure vault and a safer alternative to traditional user tables in SQL and NoSQL databases. It encrypts sensitive data (PII, PHI, PCI, KYC) and replaces it in your database with safe, random tokens — without slowing down your app’s performance.
That way, if someone breaches your system, they can’t get the real data, and you stay compliant with GDPR, CCPA, HIPAA, etc., using a simple API.
Some of Databunker Pro's enterprise security features:
* [Multi-tenancy](/pro/administration/multi-tenancy)
* [Key rotation](/pro/administration/key-rotation)
* [Shamir's secret sharing](/pro/administration/shamir-keys)
* [Format-preserving tokenization](/pro/administration/tokenization)
## Try it out for yourself
Explore common use cases in our sandbox.
# PII Vault - PII Storage & Tokenization in Databunker Pro
Source: https://docs.databunker.org/pro/get-started/pii-vault
In today's data-driven world, protecting personally identifiable information (PII) isn't just a compliance requirement—it's a business imperative. Databunker Pro's PII Vault provides enterprise-grade secure storage and tokenization for sensitive personal data, enabling organizations to build privacy-by-design solutions while maintaining operational efficiency.
When sensitive data enters your system, Databunker instantly encrypts, tokenizes, and stores it in a secure vault. You get back a safe token to store anywhere — even in public databases.
You can run Databunker in the cloud or on-premises, you can enable your enterprise customers to self-host their PII vault in any region, which solves PII export restrictions and reduces compliance risk.
## 🔐 What is a PII Vault?
The PII Vault is Databunker Pro's core feature that transforms how organizations handle sensitive personal data. Instead of storing PII directly in your application database, the PII Vault:
* **Encrypts and tokenizes** entire user records using AES-256 encryption
* **Generates secure UUID tokens** that can be safely stored anywhere
* **Maintains searchable indexes** using secure hash-based lookups
* **Provides audit trails** for every data access and modification
* **Enables compliance** with GDPR, HIPAA, SOC2, and other privacy regulations
## ⚠️ Why Use PII Vault Instead of Regular Database Tables?
### Traditional Database Approach Problems
```sql theme={null}
-- Traditional approach: PII stored in plain text or basic encryption
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email VARCHAR(255), -- Exposed in logs, backups, queries
first_name VARCHAR(100), -- Visible to all database users
last_name VARCHAR(100), -- Accessible via SQL injection
phone VARCHAR(20), -- Stored in application logs
ssn VARCHAR(11), -- High-risk data exposure
created_at TIMESTAMP
);
```
**Issues with this approach:**
* ❌ **Data exposure** in logs, backups, and error messages
* ❌ **SQL injection vulnerabilities** expose sensitive data
* ❌ **Database admin access** reveals all personal information
* ❌ **Compliance complexity** requires extensive additional controls
* ❌ **Breach impact** exposes all stored PII immediately
### Databunker Pro PII Vault Solution
Instead of storing PII in your application database, store only the user secure tokens (in UUID format):
```sql theme={null}
-- Modern approach: Only tokens stored in application database
CREATE TABLE users (
id SERIAL PRIMARY KEY,
user_token UUID -- Safe to store anywhere
);
```
**Benefits of this approach:**
* ✅ **Zero PII exposure** in application databases, logs, or backups
* ✅ **Breach protection** - attackers only see meaningless tokens
* ✅ **Built-in compliance** with privacy regulations
* ✅ **Simplified architecture** - no complex encryption management
* ✅ **Audit-ready** with comprehensive access logging
## ⚙️ How PII Vault Works
### 1. Data Ingestion and Tokenization
When sensitive data enters your system, Databunker Pro:
1. **Accepts complete user profiles** in JSON format
2. **Extracts searchable fields** (email, phone, login, custom) for indexing
3. **Encrypts the entire record** using AES-256 encryption
4. **Generates a secure UUID token** for the record
5. **Stores encrypted data** in the secure vault
6. **Creates hashed search indexes** for efficient lookups
### 2. Secure Storage Architecture
![Databunker Architecture]()
## 💻 Code Examples: Storing and Retrieving User Records
### Storing User PII
**REST API Example:**
```bash theme={null}
curl -X POST https://your-databunker-pro/v2/UserCreate \
-H "X-Bunker-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"profile": {
"email": "john.doe@example.com",
"first": "John",
"last": "Doe",
"phone": "+1-555-123-4567",
"ssn": "123-45-6789",
"address": "123 Main St, City, State 12345",
"dob": "1985-06-15"
}
}'
```
**Response:**
```json theme={null}
{
"status": "ok",
"token": "a21fa1d3-5e47-11ef-a729-32e05c6f6c16"
}
```
**JavaScript/Node.js Example:**
```javascript theme={null}
const axios = require("axios");
async function storeUserPII(userData) {
try {
const response = await axios.post(
"https://your-databunker-pro/v2/UserCreate",
{
profile: {
email: userData.email,
first: userData.firstName,
last: userData.lastName,
phone: userData.phone,
ssn: userData.ssn,
address: userData.address,
dob: userData.dateOfBirth,
},
},
{
headers: {
"X-Bunker-Token": process.env.DATABUNKER_API_KEY,
"Content-Type": "application/json",
},
}
);
return response.data.token; // Store this token in your database
} catch (error) {
console.error("Error storing user PII:", error);
throw error;
}
}
// Usage
const userToken = await storeUserPII({
email: "jane.smith@example.com",
firstName: "Jane",
lastName: "Smith",
phone: "+1-555-987-6543",
ssn: "987-65-4321",
address: "456 Oak Ave, City, State 54321",
dateOfBirth: "1990-03-22",
});
```
**Python Example:**
```python theme={null}
import requests
import json
def store_user_pii(user_data):
url = "https://your-databunker-pro/v2/UserCreate"
headers = {
"X-Bunker-Token": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"profile": {
"email": user_data["email"],
"first": user_data["first_name"],
"last": user_data["last_name"],
"phone": user_data["phone"],
"ssn": user_data["ssn"],
"address": user_data["address"],
"dob": user_data["date_of_birth"]
}
}
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
return response.json()["token"]
# Usage
user_token = store_user_pii({
"email": "mike.johnson@example.com",
"first_name": "Mike",
"last_name": "Johnson",
"phone": "+1-555-456-7890",
"ssn": "456-78-9012",
"address": "789 Pine St, City, State 67890",
"date_of_birth": "1988-11-08"
})
```
### Retrieving User PII
**Retrieve by Token:**
```bash theme={null}
curl -X POST https://your-databunker-pro/v2/UserGet \
-H "X-Bunker-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "token",
"identity": "a21fa1d3-5e47-11ef-a729-32e05c6f6c16"
}'
```
**Retrieve by Email:**
```bash theme={null}
curl -X POST https://your-databunker-pro/v2/UserGet \
-H "X-Bunker-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "email",
"identity": "john.doe@example.com"
}'
```
**Retrieve by Phone:**
```bash theme={null}
curl -X POST https://your-databunker-pro/v2/UserGet \
-H "X-Bunker-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "phone",
"identity": "+1-555-123-4567"
}'
```
## 🛡️ Enterprise Security Features
Databunker Pro provides enterprise-grade security with **AES-256 encryption**, **role-based access control**, and **comprehensive audit logging**. Built-in compliance with **DPDPA, GDPR, HIPAA, SOC2, and PCI DSS** standards, plus **multi-tenant isolation** and **horizontal scaling** for enterprise deployment.
## 🎯 Conclusion
Databunker Pro's PII Vault transforms how organizations handle sensitive data, providing enterprise-grade security that goes far beyond traditional database approaches.
**Key Benefits:**
* **🔒 Zero PII Exposure** - Sensitive data never touches your application databases, logs, or backups
* **⚡ Simplified Compliance** - Built-in GDPR, HIPAA, SOC2, and PCI DSS controls with automatic audit trails
* **🛡️ Breach Protection** - Attackers only see meaningless tokens, not actual personal data
* **🚀 Developer-Friendly** - Easy-to-use APIs that don't slow down development
* **📈 Enterprise Scale** - Horizontal scaling with multi-region deployment options
**The Bottom Line:** Instead of building complex security layers around your existing database, Databunker Pro's PII Vault eliminates the risk at the source. Your sensitive data stays secure in an encrypted vault while your applications work with safe tokens.
Ready to eliminate PII exposure and simplify compliance? The PII Vault is the modern solution for privacy-by-design architecture.
# Security overview
Source: https://docs.databunker.org/pro/get-started/security-overview
Information security's primary focus is the balanced protection of confidentiality, integrity, and availability of data. This document reviews Databunker Pro's security features based on these core principles.
Databunker Pro is built following privacy-by-design principles, which are integral to **GDPR**, **CPRA**, and **SOC2** privacy standards. **Databunker Pro** allows you to build **privacy by design** compliant solutions, and to follow data minimization requirements. When using **Databunker Pro**, every API request generates an audit trail. **Databunker Pro** can be used as a **consent management system** and as a **repository for processing operations**. It serves as an external storage according to pseudonymization definition and complies with Schrems II cross-border personal data transfer implementation.
Databunker Pro also serves as a full-featured Data Protection Officer (DPO) portal. This version includes built-in connectors for popular cloud SaaS and Databases vendors: HubSpot, MailChimp, Salesforce, MySQL, PostgreSQL, Oracle, SQL Server, and many more. Personal data reports can now be generated with a single click.
## How we address confidentiality
### Encryption in transit and encryption at rest
Databunker Pro enforces full encryption in transit and at rest by default. All network requests are secured using SSL encryption protocols.
### Record encryption
Customer personal information records are encrypted using **AES-256** keys or securely hashed in the product internal database. AES-256 encryption is **FIPS 140-2 compliant** and meets federal cryptographic standards.
### Encryption of audit events
Personally Identifiable Information (PII) in audit events is fully encrypted.
### Secure hash-based search index
Databunker Pro extracts emails, phone numbers, and login names from user records to build a hashed-based search index. This method allows secure lookups of original user records.
### Backend database connectivity
**Databunker Pro** supports both **PostgreSQL** and **MySQL** as backend databases, connecting through a **secure SSL channel**. Note: Multi-tenancy is only supported with PostgreSQL and is not available when using MySQL.
### FIPS compliance
Databunker Pro uses **FIPS 140-2 compliant** cryptographic algorithms for core security operations:
* **Certificate generation**: When deploying via Helm, certificates are generated using **RSA 2048-bit** key length, which is FIPS compliant.
* **Record encryption**: All customer records are encrypted using **AES-256**, a FIPS-approved symmetric encryption algorithm.
* **Go runtime**: The Go programming language runtime does not enforce FIPS mode internally, allowing Databunker Pro to operate in FIPS-enabled environments while maintaining compatibility.
**Note on MD5 usage**: Databunker Pro uses MD5 for non-cryptographic purposes only:
* As a distributed lock mechanism in the `users` and `userapps` tables to prevent concurrent modifications
* As part of a double-hash (SHA256 + MD5) for duplicate detection in format-preserving tokenization engine
* As salt material (MD5 of master key) for SHA256-based indexing of user records (e.g., email, phone numbers)
These MD5 usages are for internal system operations and do not impact the FIPS compliance of cryptographic operations protecting customer data.
### Secure session storage
Session data, including PII such as email addresses, IP addresses, and browser details, is securely stored in Databunker’s encrypted store via a dedicated API.
### Secure bulk data export/dump
We have introduced a specialized secure API to control and limit bulk data exports. Learn more here.
### Wrapping keys and Shamir key shares
Databunker Pro uses a **Master key** to encrypt all records. The Master Key is never exposed. In Databunker Pro, the master key is further secured using a **Wrapping key**. The wrapping key can be rotated via API, and its backup is divided into parts using the Shamir key sharing algorithm for recovery if lost or compromised.
### Optional user scheme validation
Databunker Pro supports user schema validation to enforce mandatory fields in user records. It returns error messages for objects missing required fields.
## How we address integrity
### Record update
Databunker employs encrypted JSON objects for storing user profiles. During updates, Databunker ensures the presence of the original record in the database by verifying its checksum before executing SQL UPDATE queries.
### Multi-tenancy
Databunker Pro implements multi-tenancy using PostgreSQL's row-level security mechanism. Queries executed by specific tenants are restricted to their own records. **Note:** Multi-tenancy requires PostgreSQL and is not supported with MySQL.
### Token-based API Access
All API requests require a user token and tenant name. Databunker identifies user roles, verifies permissions, and blocks unauthorized requests within the tenant’s scope.
## How we address availability
### Containers
Databunker Pro is distributed as Docker container, which can be easily deployed in cloud environments. Example scripts for running these containers using Docker Compose and Kubernetes are provided.
### Stateless application server
Databunker Pro is a stateless application server, enabling multiple instances to run concurrently. The primary bottleneck is the backend database. To address this, Databunker Pro integrates with AWS Aurora PostgreSQL Auto-Scaling databases. Both PostgreSQL and MySQL are supported as backend databases.
### Scalability in Kubernetes
Databunker Pro can be seamlessly scaled in Kubernetes using horizontal scaling. This ensures high availability and performance under increasing workloads. Kubernetes facilitates effortless scaling by dynamically adjusting the number of running instances based on resource utilization, ensuring that Databunker can meet growing demands efficiently.
# Install with Docker Compose
Source: https://docs.databunker.org/pro/installation/docker-compose
This page walks you through the steps to install Databunker Pro using Docker Compose.
## Before you start
To complete this guide, you'll need [Docker Compose](https://docs.docker.com/compose/install/) installed on your computer.
To confirm if Docker Compose is available, run the following command:
```sh theme={null}
docker compose version
```
## Clone the setup repository
The repository contains configuration and helper scripts to help you get started.
```sh theme={null}
git clone https://github.com/securitybunker/databunkerpro-setup.git
cd databunkerpro-setup
```
## Generate configuration files
In this step, you'll generate a set of environment files that will be used to configure each of the services deployed by Docker Compose.
This determines the database that Docker Compose should deploy. You don't need an existing database.
```sh theme={null}
cd docker-compose-pgsql
```
```sh theme={null}
cd docker-compose-mysql
```
The following command will create a `.env` directory containing environment files for each Docker Compose service.
```sh theme={null}
./generate-env-files.sh
```
## Deploy Databunker Pro using Docker Compose
```sh theme={null}
docker compose up -d
```
In your browser, open [localhost:3000](http://localhost:3000) to access the Databunker web interface.
For detailed instructions, see [Generate admin credentials](/pro/installation/generate-admin-credentials).
To stop all Docker Compose services and clean up resources, run the following command:
```sh theme={null}
docker compose down
```
# Generate admin credentials
Source: https://docs.databunker.org/pro/installation/generate-admin-credentials
This page explains the steps needed to set up Databunker Pro for the first time.
## Before you start
To complete this guide, you'll need:
* Databunker Pro installed
* *(Optional)* A Databunker Pro License Key.
## Copy the generated access code from the logs
When Databunker Pro starts for the first time, it generates a six-digit access code and outputs it to the service logs.
For example, if you deployed Databunker Pro on Kubernetes, you can print the access code with the following command line:
```sh theme={null}
kubectl logs deployment/databunkerpro | grep "Access code"
```
## Complete the setup in your browser
To complete the setup, you'll need access to the Databunker Pro web interface from your browser.
By default, the web interface is exposed on port 3000.
[Book a call](https://cal.com/databunker-team/30min) to purchase a license key, or leave empty to run Databunker Pro in Trial mode.
![Initial setup for Databunker Pro]()
Copy the following secrets from the page and store them securely:
* Root Access Token
* Wrapping Key
* Shamir Key Shares
![A setup page displaying root access token and encryption keys]()
Finally, click **Start Databunker Pro** to start the service.
Databunker Pro is now running and ready to use.
# Install with Kubernetes using Helm
Source: https://docs.databunker.org/pro/installation/kubernetes-helm
This page walks you through the steps to install Databunker Pro on Kubernetes using Helm.
## Before you start
To complete this guide, you'll need:
* [Kubernetes](https://kubernetes.io/docs/setup/) installed
* [Helm](https://helm.sh/docs/intro/install/) installed
## Set up the Helm repository
In this step, you'll set up the Databunker Pro Helm repository so that you can download the latest Helm charts.
```sh theme={null}
helm repo add databunkerpro https://securitybunker.github.io/databunkerpro-setup
```
```sh theme={null}
helm repo list
```
You'll see the following output:
```plain theme={null}
NAME URL
databunkerpro https://securitybunker.github.io/databunkerpro-setup
```
```sh theme={null}
helm repo update
```
You can find the Helm charts in the
[databunkerpro-setup](https://github.com/securitybunker/databunkerpro-setup)
repository.
## Deploy Databunker Pro using Helm
```sh theme={null}
helm install databunkerpro databunkerpro/databunkerpro
```
```sh theme={null}
kubectl port-forward service/databunkerpro 3000:3000
```
For more information about port-forwarding in Kubernetes, see [Use Port Forwarding to Access Applications in a Cluster](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/).
In your browser, open [localhost:3000](http://localhost:3000) to access the
Databunker web interface.
For detailed instructions, see [Generate admin credentials](/pro/installation/generate-admin-credentials).