IBEx Safe Endpoints

The IBEx Safe endpoints provide access to user data storage, email validation, and payment operations. These endpoints allow clients to manage user data in a privacy-compliant, domain-scoped manner.

User Data Transmission

During Sign-In: User data (userData) can be included in the sign-in response. To receive userData in the HTTP response, include the parameter includeUserdata: true in the request body of POST /v1.2/auth/sign-in.

Response Structure: The sign-in response includes a userdata field containing the IBEX Safe userData map:

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

Note: These endpoints can be called directly via Swagger UI:

GET /v1.2/ibexsafe/{verb}

POST /v1.2/ibexsafe/{verb}

User Data Operations

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

Parameters:

:externalUserId (string, required, path parameter): The external user identifier

Headers: Authorization (Bearer JWT)

Behavior: Read userData map for a specific external user. Returns all securely stored user data for the given externalUserId as a flat key/value map (or 204 when empty).

Response structure (200 OK):

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

Note: Privacy note: any key written via POST /v1.2/ibexsafe/userdata with the private. prefix is not returned by subsequent GET calls.

POST /v1.2/ibexsafe/userdata (read fallback)

Parameters: None

Headers: Authorization (Bearer JWT)

Body:

externalUserId (string, required): The external user identifier
data (object, required): Empty object {}

Behavior: Provider supports POST to read when GET external is unauthorized (fallback on 401). Used when GET endpoint returns 401 unauthorized.

Response structure (200 OK):

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

POST /v1.2/ibexsafe/userdata (write)

Parameters: None

Headers: Authorization (Bearer JWT)

Body:

externalUserId (string, required): The external user identifier
data (object, required): Record of key/value pairs to update. Values can be string, boolean, number, or null (to delete keys)

Behavior: Update userData keys. Used by multiple backend endpoints (update-language, update-contact, update-wire, reference-attach, update-userdata, update-optin).

Request example:

{
  "externalUserId": "ext_user_123",
  "data": {
    "firstName": "Jane",
    "lastName": "Doe",
    "language": "en",
    "optin.newsletter": true,
    "optin.walletAlerts": false,
    "oldKey": null
  }
}

Response structure (200 OK):

{
  "success": true,
  "message": "User data updated"
}

Email Validation

POST /v1.2/ibexsafe/validateEmail

Parameters: None

Headers: Authorization (Bearer JWT)

Body:

email (string, required): Email address to validate
externalUserId (string, required): The external user identifier

Behavior: Start email verification; sends verification code to the provided email address.

Request example:

{
  "email": "jane.doe@foo.domain",
  "externalUserId": "ext_user_123"
}

Response structure (200 OK):

{
  "success": true,
  "message": "Verification code sent to email"
}

POST /v1.2/ibexsafe/confirmEmail

Parameters: None

Headers: Authorization (Bearer JWT)

Body:

email (string, required): Email address to confirm
code (string, required): Verification code received via email
externalUserId (string, required): The external user identifier
userDataName (string, optional): Key name to store the confirmed email in userData
optinNews (boolean, optional): Opt-in for news updates
optinNotifications (boolean, optional): Opt-in for notifications

Behavior: Confirm email with verification code, optionally persisting under a specific userData key.

Request example:

{
  "email": "jane.doe@foo.domain",
  "code": "123456",
  "externalUserId": "ext_user_123",
  "userDataName": "email",
  "optinNews": true,
  "optinNotifications": true
}

Response structure (200 OK):

{
  "success": true,
  "message": "Email confirmed",
  "email": "jane.doe@foo.domain"
}

Payment Operations

POST /v1.2/ibexsafe/pay (WIP)

Parameters: None

Headers: Authorization (Bearer JWT)

Body:

externalUserId (string, required): The external user identifier
amount (number, required): Payment amount in cents
language (string, required): Language code ('fr' or 'en')
userTransactionId (string, required): Unique transaction identifier (18 characters)
cbFeePercentage (number, required): Card fee percentage

Behavior: Initiate a card payment. Used by backend POST /api/card-payment/pay.

Request example:

{
  "externalUserId": "ext_user_123",
  "amount": 10000,
  "language": "en",
  "userTransactionId": "tx_123456789012345",
  "cbFeePercentage": 2.5
}

Response structure (200 OK):

{
  "paymentId": "pay_abc123",
  "status": "initiated",
  "redirectUrl": "https://payment-provider.com/checkout/..."
}

Privacy Note: Any key written via POST /v1.2/ibexsafe/userdata with the authenticated user's externalUserId is stored in a privacy-compliant, domain-scoped manner. The data is only accessible within the same rpId (tenant) context. Keys prefixed with private. are not returned by GET operations.