Skip to content
Hubble logo Hubble logo Hubble Documentation

SSO Integration

SDK - SSO Integration Instructions

When Hubble’s SDK is invoked, we need to create a proxy user in our system. All our API calls would be happening against the session id we generate for this proxy user.

To create this proxy user, we require our partners to expose an API through which we can get user’s details.

Some of the mandatory user fields we require are

  1. User’s id
  2. Name
  3. Phone number

These are mandatory because we need to pass this to some of the services that power Hubble.

In the frontend, your application can pass to our SDK some code or token that uniquely identifies the user.

When the SDK is initialised,

  1. Our backend will get the token
  2. Make a call to the above requested API to get the user details
  3. Create user and session and return the session id for our SDK to start voucher workflows.

API Request/Response

Request

POST /sso

Headers:

  • X-Hubble-Secret (string, required) — Pre-shared secret provided during onboarding

Body:

  • token (string, required) — SSO token generated by the partner system. Token validation logic is fully owned by the partner.

Response (200 OK):

{
  "userId": "test-user-123",
  "email": "testuser@example.com",
  "firstName": "Test",
  "lastName": "User",
  "phoneNumber": "1234567890",
  "cohorts": ["premium", "beta"]
}

Response Fields:

  • userId (string, nullable) — Partner’s unique user identifier. Must be present for a valid token.
  • email (string, optional)
  • firstName (string, optional)
  • lastName (string, optional)
  • phoneNumber (string, optional)
  • cohorts (array of strings, optional) — Logical user groups used for segmentation, eligibility, or feature access.

Invalid Token Response (401 or 400):

If the token is invalid or expired, return:

{
  "userId": null
}

Returning userId = null indicates authentication failure.

Example:

Terminal window
curl -X POST "https://partner-api.example.com/sso" \
  -H "X-Hubble-Secret: your-secret-key" \
  -H "Content-Type: application/json" \
  --data '{"token": "sso-token"}'

Note: The partner is expected to implement this interface and share the base URL with our team. Our system will invoke the /sso API endpoint using the provided base URL.

Sequence Diagram

SSO sequence diagram