User Data Storage - Integration Guide

This guide explains how to store and retrieve private user data using IBEX Safe's secure storage service. IBEX Safe is a regulated entity (VASP) compliant with GDPR, allowing your dApp to manage users' private data without ever storing it yourself.

📊 View Flow Diagram

Overview

The User Data API uses a generic proxy pattern to route requests to IBEX Safe. The IBEx.Fi API provides a transparent proxy endpoint that forwards requests to the IBEX Safe API, which handles the actual data storage and retrieval.

The proxy endpoints are:

GET /v1.1/ibexsafe/:verb : Generic proxy for IBEX Safe GET requests (where :verb is userdata/external/:externalUserId)
POST /v1.1/ibexsafe/:verb : Generic proxy for IBEX Safe POST requests (where :verb is userdata, validateEmail, confirmEmail, etc.)

For user data operations, you call:

POST /v1.1/ibexsafe/userdata : Store/update user data - routes to IBEX Safe /userdata
GET /v1.1/ibexsafe/userdata/external/:externalUserId : Retrieve user data - routes to IBEX Safe /userdata/external/:externalUserId

The User Data API allows you to:

Store private user data securely in IBEX Safe (key/value pairs)
Retrieve stored user data for authenticated users
Update existing user data (partial updates supported)
Protect sensitive data with the private. prefix (not returned on GET)

💡 Proxy Pattern :

The IBEx.Fi API acts as a transparent proxy - all parameters are forwarded to IBEX Safe as documented in IBEX Safe Endpoints
Authentication is validated by IBEx.Fi API before proxying to IBEX Safe
All IBEX Safe endpoints are accessible through the generic proxy pattern

🔒 Privacy & Security :

Data is stored in IBEX Safe, a GDPR-compliant regulated entity
Your dApp never stores user data directly
Keys prefixed with private. are write-only and never returned on GET requests
All operations require JWT authentication

1. Store User Data

To store or update user data, use the POST /v1.1/ibexsafe/userdata endpoint. This routes through the generic proxy to IBEX Safe's /userdata endpoint.

Endpoint : POST /v1.1/ibexsafe/userdata (via generic proxy POST /v1.1/ibexsafe/:verb)

Headers :

Authorization: Bearer <access_token> (required)
Content-Type: application/json (required)

Body (JSON) :

externalUserId (string, required) : The external user identifier (from JWT)
data (object, required) : Key/value pairs to store. Values can be:
- string : Text values (e.g., email, names, addresses)
- boolean : Boolean flags (e.g., opt-in preferences)
- number : Numeric values
- null : To delete a key (set to null)

Request Example :

POST /v1.1/ibexsafe/userdata
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {
    "email": "jane.doe@foo.domain",
    "firstName": "Jane",
    "lastName": "Doe",
    "language": "en",
    "optin.newsletter": true,
    "optin.walletAlerts": true,
    "private.apiKey": "secret-api-key-12345"
  }
}

Response (200 OK) :

{
  "success": true
}

💾 To Store :

No specific data to store from the response - the operation is idempotent
You can call this endpoint multiple times to update data incrementally

💡 Note :

Partial updates are supported - you only need to include the keys you want to update
To delete a key, set its value to null
Keys prefixed with private. are write-only and will never be returned on GET requests

Common Use Cases

User Profile Information :

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {
    "email": "jane.doe@foo.domain",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+33612345678",
    "language": "en"
  }
}

Opt-in Preferences :

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {
    "optin.newsletter": true,
    "optin.walletAlerts": true,
    "optin.marketing": false
  }
}

Private/Sensitive Data :

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {
    "private.apiKey": "secret-key-12345",
    "private.encryptionKey": "encrypted-data-here",
    "private.customSecret": "sensitive-information"
  }
}

⚠️ Important : Keys prefixed with private. are write-only. They can be stored but will never be returned when retrieving user data. Use this for sensitive information that should never be exposed via GET requests.

2. Retrieve User Data

To retrieve stored user data, use the GET /v1.1/ibexsafe/userdata/external/:externalUserId endpoint. This routes through the generic proxy to IBEX Safe's /userdata/external/:externalUserId endpoint.

Endpoint : GET /v1.1/ibexsafe/userdata/external/:externalUserId (via generic proxy GET /v1.1/ibexsafe/:verb)

Headers :

Authorization: Bearer <access_token> (required)

Path Parameters :

externalUserId (string, required) : The external user identifier (from JWT)

Request Example :

GET /v1.1/ibexsafe/userdata/external/c76302cb-f845-40f4-9c56-29710323afba
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "email": "jane.doe@foo.domain",
  "firstName": "Jane",
  "lastName": "Doe",
  "language": "en",
  "optin.newsletter": true,
  "optin.walletAlerts": true
}

💡 Note :

Keys prefixed with private. are not included in the response
If no data exists, the endpoint returns 204 No Content
The response is a flat key/value map (no nested objects)

Fallback: POST for Reading

If the GET endpoint returns 401 Unauthorized, you can use POST as a fallback:

Endpoint : POST /v1.1/ibexsafe/userdata

Body (JSON) :

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {}
}

Response (200 OK) :

{
  "email": "jane.doe@foo.domain",
  "firstName": "Jane",
  "lastName": "Doe",
  "language": "en",
  "optin.newsletter": true,
  "optin.walletAlerts": true
}

3. Update User Data

To update existing user data, use the same POST /v1.1/ibexsafe/userdata endpoint with partial data. Only the keys you include will be updated.

Request Example (Partial Update) :

POST /v1.1/ibexsafe/userdata
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {
    "language": "fr",
    "optin.newsletter": false
  }
}

Response (200 OK) :

{
  "success": true
}

💡 Note : Partial updates are supported. You only need to include the keys you want to update. Other keys remain unchanged.

Delete a Key

To delete a key, set its value to null:

POST /v1.1/ibexsafe/userdata
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "externalUserId": "c76302cb-f845-40f4-9c56-29710323afba",
  "data": {
    "phone": null,
    "optin.marketing": null
  }
}

4. Integration with Sign-In

You can optionally include user data in the sign-in response by setting includeUserdata: true in the sign-in request body:

Request Example :

POST /v1.2/auth/sign-in
Content-Type: application/json

{
  "credential": { ... },
  "includeUserdata": true
}

Response (200 OK) :

{
  "access_token": "...",
  "refresh_token": "...",
  "safeAddress": { ... },
  "userdata": {
    "email": "jane.doe@foo.domain",
    "firstName": "Jane",
    "lastName": "Doe",
    "language": "en",
    "optin.newsletter": true,
    "optin.walletAlerts": true
  }
}

💡 Note : This is optional. If includeUserdata is not set or is false, the userdata field will not be included in the response.

5. Error Handling

401 Unauthorized

If the JWT is missing or invalid, you will receive a 401 error. Make sure to include a valid Authorization header.

400 Bad Request

If the request body is malformed or externalUserId doesn't match the authenticated user, you will receive a 400 error.

404 Not Found

If the user data doesn't exist, GET requests return 204 No Content (not 404).

6. Complete Flow Summary

Store initial data : POST /v1.1/ibexsafe/userdata with user data
Retrieve data : GET /v1.1/ibexsafe/userdata/external/:externalUserId to get stored data
Update data : POST /v1.1/ibexsafe/userdata with partial updates as needed
Optional: Include in sign-in : Set includeUserdata: true in sign-in requests

⚠️ Important Points :

All operations require JWT authentication
Data is stored securely in IBEX Safe (GDPR-compliant)
Keys prefixed with private. are write-only and never returned
Partial updates are supported - only include keys you want to change
Set a key to null to delete it
The externalUserId must match the authenticated user from the JWT

Technical Deep Dive - For AI Integration

This section provides detailed technical information for AI systems integrating the IBEX User Data storage flow, including architecture patterns, data models, and implementation details.

User Data Storage - Technical Details

Generic Proxy Pattern

The IBEx.Fi API provides generic proxy endpoints: GET /v1.1/ibexsafe/:verb and POST /v1.1/ibexsafe/:verb
For user data, :verb is userdata or userdata/external/:externalUserId, so you call POST /v1.1/ibexsafe/userdata or GET /v1.1/ibexsafe/userdata/external/:externalUserId
The proxy forwards all query parameters, headers, and body to IBEX Safe without modification
IBEX Safe handles the actual data storage and retrieval according to its own API documentation
See IBEX Safe Endpoints for complete IBEX Safe API documentation

POST /v1.1/ibexsafe/userdata

Endpoint: Generic proxy POST /v1.1/ibexsafe/:verb with verb=userdata
Routes to: IBEX Safe POST /userdata
Authentication: JWT required (validated by IBEx.Fi API before proxying)
Body validation: externalUserId must match authenticated user (validated by IBEx.Fi API)
Data format: Flat key/value pairs (no nested objects) - forwarded to IBEX Safe
Value types: string, boolean, number, null - all forwarded to IBEX Safe
Privacy: Keys with private. prefix are write-only (handled by IBEX Safe)
Idempotency: Multiple calls with same data are safe (handled by IBEX Safe)
Partial updates: Only included keys are updated (handled by IBEX Safe)
Deletion: Set key to null to delete (handled by IBEX Safe)
Response format: Success confirmation (as returned by IBEX Safe)

GET /v1.1/ibexsafe/userdata/external/:externalUserId

Endpoint: Generic proxy GET /v1.1/ibexsafe/:verb with verb=userdata/external/:externalUserId
Routes to: IBEX Safe GET /userdata/external/:externalUserId
Authentication: JWT required (validated by IBEx.Fi API before proxying)
Response format: Flat key/value map (as returned by IBEX Safe)
Privacy: Keys with private. prefix are excluded (handled by IBEX Safe)
Empty response: Returns 204 No Content if no data exists (as returned by IBEX Safe)
Fallback: POST with empty data: {} can be used if GET returns 401 (handled by IBEX Safe)

Data Model

User Data Structure:

{
  "externalUserId": "string (UUID)",
  "data": {
    "key1": "string | boolean | number | null",
    "key2": "string | boolean | number | null",
    "private.secretKey": "string | boolean | number | null"  // Write-only
  }
}

Common Keys (Examples):

email : User email address
firstName : User first name
lastName : User last name
language : Preferred language (e.g., "en", "fr")
phone : Phone number
optin.newsletter : Newsletter opt-in (boolean)
optin.walletAlerts : Wallet alerts opt-in (boolean)
optin.marketing : Marketing opt-in (boolean)
private.apiKey : Private API key (write-only)
private.encryptionKey : Private encryption key (write-only)

Privacy & Security

Private Keys:

Keys prefixed with private. are write-only
They can be stored via POST but are never returned on GET
Use for sensitive data that should never be exposed
Examples: API keys, encryption keys, secrets, tokens

GDPR Compliance:

Data is stored in IBEX Safe, a regulated entity (VASP)
IBEX Safe is GDPR-compliant
Your dApp never stores user data directly
All operations are logged for audit purposes

Integration Points

Sign-In Integration:

Set includeUserdata: true in sign-in request body
User data is included in sign-in response as userdata field
Reduces need for separate GET request after sign-in
Non-blocking: If user data fetch fails, sign-in still succeeds

WebSocket Integration:

User data can be pushed via WebSocket on sign-in
WebSocket message type: user_data
Automatically sent when WebSocket clients are connected

Error Handling

401 Unauthorized : Invalid or missing JWT
400 Bad Request : Malformed request body, invalid externalUserId
404 Not Found : User not found (rare, usually 401 instead)
204 No Content : No user data exists (GET only)
500 Internal Server Error : IBEX Safe API error, network error

Key Implementation Files

src/routes/v1.1/ibexsafe.ts : User data endpoints (POST/GET proxies)
src/clients/IbexSafe.ts : IBEX Safe API client
src/routes/v1/auth.ts : Sign-in integration with includeUserdata

Complete Flow - Technical Sequence

Store data : POST /v1.1/ibexsafe/userdata with { externalUserId, data: { key: value } }
Proxy to IBEX Safe : API forwards request to IBEX Safe upstream
Data stored : IBEX Safe stores data securely (GDPR-compliant)
Retrieve data : GET /v1.1/ibexsafe/userdata/external/:externalUserId
Proxy to IBEX Safe : API forwards GET request to IBEX Safe
Filter private keys : IBEX Safe excludes private.* keys from response
Return data : API returns flat key/value map to client
Update data : POST /v1.1/ibexsafe/userdata with partial updates
Delete key : Set key to null in update request

← Back to Main Guide