BoxOwl PDaaS Architecture
High-level design for Personal Data as a Service — how organizations integrate with BoxOwl's multi-tenant vault, consent model, and compliance infrastructure.
System Layers
Integration Layer
- PDaaS Customer App — Your web or mobile application
- Webhook Endpoint — Your server receives event notifications
- Employee Dashboard — Org admins manage keys, members, and settings
Auth: X-API-Key: boxlive_...
BoxOwl Platform
- BoxOwl API — REST API at api.boxowl.me/api/v1
- Consent Layer — Grants/revokes, scope management
- Vault Data — Per-user encrypted vaults with row isolation
- Webhook Delivery — Retry logic, delivery tracking, DLQ
- Audit Logging — Access records, activity history
Auth: JWT (user) + X-API-Key (org)
PDaaS Customer
- Organization — Tenant root with members and billing
- API Keys — Scoped keys per environment
- Connected Customers — End users who granted consent
- Organization Employees — Admins and developers
End Users
- Individual Users — People with BoxOwl accounts
- Encrypted Vault — Per-user data: identity, addresses, credentials
- Unified Control Plane — One dashboard to manage all org connections
User always owns their data
Key Data Flows
API Key Authentication
Your application authenticates to the BoxOwl API using an organization API key prefixed bxorg_, passed as a Bearer token on every request.
curl https://api.boxowl.me/api/v1/connect/users/kira/address/primary -H "Authorization: Bearer bxorg_01h455..."
End User Grants Consent
Your customer connects their BoxOwl account to your app. BoxOwl presents a clear consent prompt showing exactly what data categories you can access and why. The user accepts, creating a connection record.
The consent is stored by BoxOwl and can be revoked by the user at any time from their BoxOwl app.
API Access to User Vault
With an active connection and appropriate scopes, your API key can read/write the user's vault. Access is strictly limited to categories the user consented to — unshared categories return 403 Forbidden.
Every operation is logged with your key ID, the user ID, timestamp, and IP address.
Webhook Event Notifications
BoxOwl pushes events to your webhook endpoint when vault data changes or consent is modified. Events include customer.connection-established, customer.connection-revoked, customer.vault.updated, and customer.vault.deletion-pending.
Failed deliveries retry with exponential backoff (5 retries, 30s base). Dead letter queue after max retries.
Audit Log Export
Every read, write, and delete is recorded with actor, timestamp, IP, resource, and outcome. Inspect via the paginated GET /api/v1/admin/audit-log endpoint.
PDaaS Consent Scopes
BoxOwl uses a consent-scope model, not per-key permissions. Your org's bxorg_* key authenticates the app; what data it can actually reach is gated by the user's connection record, which lists the scopes that user has granted to you. Reads use the bare scope name; writes require the explicit :write verb, granted separately at consent time.
| Scope | Description | Example Use |
|---|---|---|
identity.name |
First, last, preferred, and display name | Personalize a checkout receipt |
identity.email |
Primary email and verified flag | Send order confirmation |
identity.verified |
BoxOwl verification status | Bypass extra KYC for verified users |
address.primary |
Primary postal address (Pattern A — atomic) | Default shipping/billing address |
address.shipping |
Addresses flagged shipping | Address picker at checkout |
address.list |
Full address-book (Pattern B — CRUD) | Vault-mirrored address manager |
contact.phone |
Primary phone number | SMS order alerts |
social.links |
Curated public profile links | Auto-fill a profile page |
work.history |
Job titles, employers, dates | Resume import |
preferences.general |
UI preferences and settings | Carry preferences across apps |
preferences.dietary |
Dietary restrictions and preferences | Filter restaurant search results |
Append :write to any scope (e.g., address.primary:write) to grant the app permission to update that field. Writes use the same gateway routes (PUT / POST / PATCH / DELETE) and are subject to the same connection-record check; missing the write verb returns 403 scope_missing.
Webhook Delivery Architecture
Retry logic: Failed deliveries retry at 30s, 60s, 120s, 240s, 480s (exponential backoff × 2).
Dead letter queue: After 5 failed attempts, the event is moved to DLQ. Inspect and replay from the org dashboard.
Signature verification: Each delivery includes X-BoxOwl-Signature: sha256=... for HMAC-SHA256 verification using your webhook secret.
Timeout: Your endpoint must respond within 10 seconds. Return 2xx to acknowledge; return 4xx to indicate non-retryable failure.
Compliance Built In
CCPA/CPRA
Export and erasure endpoints ready. Data processor agreement included.
GDPR Ready
Legal basis tracking, retention periods, right-to-erasure pipeline.
Audit Trail
Every access logged: actor, key ID, timestamp, IP, resource.
Deletion Lifecycle
30-day grace period. Early close when all orgs confirm. User notified.
Data Map
GET /orgs/{slug}/data-map returns all categories with legal basis.
Row Isolation
Multi-tenant: customer vaults isolated by user ID, no cross-tenant access.
View the full source diagram in Excalidraw — pdaas-architecture.excalidraw.json