Welcome to the Hubby API documentation. This API enables partners to seamlessly integrate eSIM booking and management capabilities into their applications.
Key Features:
The API supports four types of packages:
Starter packages: Hybrid packages that are both data and time limited. They provide a small data allowance within a short time period (default: 2 days). Perfect for first-time users and trials.
Data-limited packages: Traditional packages with a specific data allowance that expires after a certain period (default: 365 days). This is the primary package type and the default for most use cases.
Unlimited packages: Packages that provide unrestricted data usage for a specified duration. Subject to fair use policy. Ideal for heavy data users and digital nomads.
Time-limited packages: Packages that provide a fixed data allowance for a specific duration with full-speed access. These packages expire when either the data limit or time limit is reached.
Note: Top-ups are always data-limited packages, regardless of the original package type.
Authentication: All API requests must include the following headers:
The HMAC signature must be generated for each request using:
Note: Swagger UI cannot be used to test the API directly as each request requires a unique HMAC signature. Please implement the authentication in your client application.
Example Node.js Implementation:
const cryptoJs = require('crypto-js');
// Configuration values that would normally come from environment
const secretKey = "YOUR_API_SECRET";
const publicKey = "YOUR_API_KEY";
const baseUrl = "YOUR_BASE_URL";
// Function to generate headers for API request
function generateApiHeaders(method, path) {
//Timestamp is in milliseconds e.g. 1715558400000
const timestamp = Math.floor(Date.now()).toString();
// Ensure url is a string
let path = String(url);
// Remove baseUrl from the url if present
path = processedUrl.replace(baseUrl, '');
// Create query string if needed
const queryString = new URL(url).search;
if (queryString) {
processedUrl += queryString;
}
// Validate public key
if (!publicKey) {
throw new Error("Public key is required");
}
// Create the payload
// Sample payload: 1715558400000GET/bookings?bookingId=1234567890
const payload = timestamp + method + path;
// Generate the HMAC signature
const signature = cryptoJs.HmacSHA256(payload, secretKey).toString(cryptoJs.enc.Hex);
// Return headers object
return {
'x-timestamp': timestamp,
'x-signature': signature,
'x-api-key': publicKey,
'Accept': 'application/json'
};
}Need Help?
Generates a short-lived redirect token that the partner app uses to open the Hubby WebView. The token is valid for 5 minutes and is single-use.
When to call: Every time the traveler opens the eSIM section in your app. Do not cache the returned token — generate a fresh token on every open, on app resume, and if the 5-minute window expires.
Authentication: HMAC-SHA256 (same as all partner endpoints).
The partner's own user identifier — your internal ID for this traveler. This is not Hubby's user_id from the booking API.
curl -i -X POST \
https://docs.hubbyesim.com/_mock/apis/v2_0_0/openapi/redirect-tokens/create \
-H 'Content-Type: application/json' \
-d '{
"external_user_id": "partner_user_456",
"redirect_token": "b3864ab6-c13b-42b5-9f69-935eb9c34aba"
}'{ "success": true, "data": { "redirect_token": "1b80dfe9-0202-4151-a26f-ceac52ca3b34", "expires_in": 300 } }
Exchanges a redirect token for a short-lived session JWT. The JWT is used as a Bearer token for all subsequent WebView API calls.
Called automatically by the Hubby WebView — partners do not call this endpoint directly. Documented for transparency and to aid debugging of WebView network traffic.
Authentication: None (the redirect token itself is the credential).
The redirect token returned by /redirect-tokens/create.
curl -i -X POST \
https://docs.hubbyesim.com/_mock/apis/v2_0_0/openapi/webapp/auth/exchange \
-H 'Content-Type: application/json' \
-d '{
"redirect_token": "1b80dfe9-0202-4151-a26f-ceac52ca3b34",
"external_user_id": "123"
}'{ "success": true, "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 1209600 } }
Returns the authenticated traveler's dashboard data: active packages, data usage, unclaimed packages, and available actions.
Called automatically by the Hubby WebView — partners do not call this endpoint directly. Documented for transparency and to aid debugging of WebView network traffic.
Authentication: Bearer JWT from /webapp/auth/exchange.
curl -i -X GET \
https://docs.hubbyesim.com/_mock/apis/v2_0_0/openapi/webapp/me/dashboard \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'{ "success": true, "data": { "unclaimed_packages": [ … ], "active_packages": [ … ], "expired_packages": [ … ] } }
Assigns a fresh universal eSIM to a user identified by external_user_id. If the user already has a universal eSIM, it is replaced with a new one. If the user does not yet have one, a new eSIM is provisioned and assigned.
Use this endpoint to pre-provision an eSIM for a traveler before they open the WebView, or to replace a problematic eSIM with a fresh one.
Authentication: Bearer JWT from /webapp/auth/exchange.
curl -i -X POST \
https://docs.hubbyesim.com/_mock/apis/v2_0_0/openapi/webapp/refresh-esim \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"external_user_id": "partner_user_456"
}'{ "success": true, "data": { "iccid": "8901234567890123456", "qr": "LPA:1$smdp.example.com$ACTIVATION-CODE", "status": "RELEASED" } }