# Whitelabel eSIM platform integration guide A technical overview for partners integrating the Airalo White Label e-commerce platform on their own domain. ## Table of contents - [The goal: a seamless brand experience](#the-goal-a-seamless-brand-experience) - [The solution: reverse proxy architecture](#the-solution-reverse-proxy-architecture) - [Platform services overview](#platform-services-overview) - [End-user data flow deep dive](#end-user-data-flow-deep-dive) - [Email communication setup](#email-communication-setup) - [Who does what? A clear breakdown](#who-does-what-a-clear-breakdown) - [Reverse proxy technology](#reverse-proxy-technology) - [Key benefits of this approach](#key-benefits-of-this-approach) - [Frequently asked questions](#frequently-asked-questions) - [Next steps & requirements](#next-steps--requirements) ## The goal: a seamless brand experience This document explains how to integrate the Airalo White Label e-commerce platform so it's served directly from your partner domain. The architecture is designed to meet three key requirements for a successful partnership. | | | | --- | --- | | 🔗 **Seamless user experience** | Users see your domain (e.g. `airgsm.com`) in the address bar at all times, ensuring brand consistency and trust. | | ⚙️ **Full partner control** | You retain complete control over your domain's SEO, traffic analytics, and routing rules. | | 🛡️ **Robust security** | The direct platform instance is shielded from public access, protecting your integration. | ## The solution: reverse proxy architecture The integration is achieved using a **reverse proxy**. This is a standard, secure, and highly effective architecture for White Label solutions. Your reverse proxy server acts as the "front door" for your domain. It receives all user traffic and intelligently forwards it to the Airalo platform, while ensuring your domain remains in the user's address bar. This process is completely invisible to the end-user. ## Platform services overview The White Label solution consists of two distinct services, each with a specific audience and interaction flow. In the diagrams below, blue marks infrastructure you own and coral marks services Airalo runs. ### Management flow ```mermaid flowchart LR A["Partner employees
Your team"] --> B["Partner Platform
Admin backend, SSO"] classDef user fill:#F1EFE8,stroke:#9A9890,color:#2C2C2A; classDef partner fill:#E6F1FB,stroke:#378ADD,color:#0C447C; classDef airalo fill:#FAECE7,stroke:#D85A30,color:#712B13; class A user; class B airalo; ``` **Partner Platform** is your secure administrative backend to manage the e-shop, set prices, control inventory, review support requests, and configure payment information. Access can be integrated with your SSO. ### Customer flow ```mermaid flowchart LR A["End users
Your customers"] --> B["Your reverse proxy
Your infrastructure"] --> C["White Label Storefront
Customer-facing e-shop"] classDef user fill:#F1EFE8,stroke:#9A9890,color:#2C2C2A; classDef partner fill:#E6F1FB,stroke:#378ADD,color:#0C447C; classDef airalo fill:#FAECE7,stroke:#D85A30,color:#712B13; class A user; class B partner; class C airalo; ``` **White Label Storefront** is the customer-facing e-shop where users browse, purchase, top-up, and manage their eSIMs under your brand, accessed seamlessly via your domain. ## End-user data flow deep dive How a customer's request to the White Label Storefront travels through the system. The request flows down through your infrastructure into Airalo's; the response retraces the same path back, so the browser only ever shows your domain. ```mermaid flowchart TD A["End user's browser
1. Types airgsm.com"] --> B subgraph Partner["Partner infrastructure"] B["DNS for airgsm.com
2. Resolves to proxy IP"] --> C["Reverse proxy
3. Forwards to origin"] end C --> D subgraph Airalo["Airalo infrastructure"] D["Firewall
4. IP whitelist check"] --> E["White Label Storefront
5. Builds the page"] end E -.->|"6-7. Response retraces the path;
browser still shows airgsm.com"| A classDef user fill:#F1EFE8,stroke:#9A9890,color:#2C2C2A; classDef partner fill:#E6F1FB,stroke:#378ADD,color:#0C447C; classDef airalo fill:#FAECE7,stroke:#D85A30,color:#712B13; class A user; class B,C partner; class D,E airalo; style Partner fill:none,stroke:#378ADD,stroke-dasharray:5 5,color:#185FA5; style Airalo fill:none,stroke:#993C1D,stroke-dasharray:5 5,color:#993C1D; ``` 1. **User request** — an end-user types `https://airgsm.com` into their browser. 2. **DNS resolution** — the partner's DNS points the domain to the public IP of their reverse proxy. 3. **Proxy receives & forwards** — the reverse proxy receives the request and forwards it to the Airalo White Label Storefront's origin URL. 4. **IP whitelist check** — the Airalo firewall checks that the request is from the partner's whitelisted proxy IP. 5. **Platform response** — the Airalo storefront processes the request and sends the e-shop page back to the proxy. 6. **Response relay** — the response travels back from the Airalo firewall to the partner's proxy. 7. **Final response** — the proxy serves the page to the user, who still sees `https://airgsm.com` in their browser. ## Email communication setup To maintain brand consistency, transactional emails (like order confirmations) must come from your domain. The Airalo platform uses Postmark for reliable delivery. You have two options to authorize the Airalo platform to send emails on your behalf. ### Option 1: Full domain verification (recommended) 👍 **How it works:** You add specific DNS records (DKIM and Return-Path) that Airalo provides to your domain's configuration. This is the industry-standard method for maximum email deliverability and security. It allows the Airalo platform to send emails from any address on your domain (e.g. `support@airgsm.com`), providing full flexibility. ### Option 2: Single email address verification **How it works:** Provide a single email address to Airalo. Postmark will send a verification link to this address, which you must click. This is a simpler setup but is less flexible. The Airalo platform will only be able to send emails from that one exact address. ## Who does what? A clear breakdown Successful integration is a partnership with a clear division of ownership: **you own the edge** (your domain, proxy, certificates, and analytics), while **Airalo owns the platform** (the storefront and Partner Platform, their availability, and the firewall). The detailed responsibilities for each party are below. ### Partner's responsibilities - **DNS management** — point domain's A or CNAME records to your proxy server. - **Reverse proxy** — procure, configure, and maintain the proxy server. - **SSL certificate** — manage and install the SSL certificate for your domain. - **Email verification** — add DNS records or verify a single sender email address. - **SEO & traffic control** — implement analytics, caching, and SEO rules on your proxy. - **Cookie/consent management** — provide the script for your consent management tool. ### Airalo's responsibilities - **Admin access to Partner Platform** — provide administration access to Partner Platform, to allow the partner to configure SSO/SCIM or manually onboard their team. - **Platform availability** — ensure uptime and performance of both the Partner Platform and Storefront. - **Provide origin URL** — supply the stable URL for your White Label Storefront instance. - **IP whitelisting** — securely maintain the list of approved partner IP addresses. - **Provide email DNS records** — supply the correct DKIM and Return-Path records. ## Reverse proxy technology The reverse proxy architecture is flexible and can be implemented using a variety of modern proxy servers. Common choices include **Nginx**, **HAProxy**, **Caddy**, and **Traefik**. The Airalo team can provide guidance based on your specific technical environment. ### Example configuration ⚠️ **This is an illustrative example, not a production-ready config.** It shows the essential pieces that make domain-masking work, but every environment differs. Please review and adapt it together with your own platform/infrastructure team before deploying, and treat values like the origin URL, timeouts, and header handling as placeholders to confirm with Airalo. The two things that most commonly break a White Label setup are the `Host` header (the storefront needs to know which brand is being served) and the forwarded-client headers (so the platform sees the real visitor, not your proxy). A minimal Nginx `server` block illustrating the idea: ```nginx # EXAMPLE ONLY — confirm all values with your platform team and Airalo server { listen 443 ssl; server_name airgsm.com; # Your domain's certificate (you manage this — see SSL note below) ssl_certificate /etc/ssl/airgsm/fullchain.pem; ssl_certificate_key /etc/ssl/airgsm/privkey.pem; location / { # Origin URL is supplied by Airalo for your storefront instance proxy_pass https://your-storefront-origin.airalo.example; # Keep your brand domain as the Host the platform sees proxy_set_header Host airgsm.com; # Pass the real visitor details through to the platform proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; # Validate the upstream TLS connection to the Airalo origin proxy_ssl_server_name on; } } ``` The exact directives, header names, and TLS settings depend on your chosen proxy and Airalo's origin requirements — use this only as a conversation starter with your platform team. ### A note on SSL/TLS There are two separate TLS connections in this setup, and it's worth confirming both with Airalo: - **Visitor → your proxy** — you manage and install the certificate for your own domain (e.g. `airgsm.com`). This is the certificate end-users see. - **Your proxy → Airalo origin** — your proxy should connect to the Airalo origin URL over HTTPS and validate that connection (`proxy_ssl_server_name` in the example above). Confirm with Airalo whether anything specific is expected on this leg. ## Key benefits of this approach - 🎨 **Full brand consistency** — the user journey, from website to email, happens entirely on your domain. - 📈 **Complete SEO control** — manage meta tags, `robots.txt`, and sitemaps directly on your proxy. - 🔒 **Enhanced security** — IP whitelisting prevents unauthorized scraping and direct access. Note that this whitelist is effectively the only barrier between the public internet and the storefront origin, so keeping your proxy's IP list accurate and up to date is critical: if it drifts, you risk either exposing the origin or breaking your own storefront. - 📊 **Flexibility & analytics** — integrate your own analytics, caching, or even a Web Application Firewall. ## Frequently asked questions This is a key benefit of the reverse proxy model. You have full control over how your domain is presented to search engines. Your proxy can manage your `robots.txt` and `sitemap.xml` files, implement 301/302 redirects, and even modify HTTP headers for advanced SEO tactics. This gives you complete authority over your search engine presence. This responsibility is shared. The Airalo White Label Storefront provides the core e-shop page with a well-structured and semantic use of header tags. Your team then controls the final output via the reverse proxy. While you can't change the platform's core HTML, you can override metadata like the page title or inject structured data (like JSON-LD for rich snippets) to enhance the base provided by Airalo. Yes, and it is expected. As part of your responsibilities, you will provide the script for your cookie and consent management platform. Similarly, you can use your reverse proxy to inject your own analytics scripts (e.g. Google Analytics, Adobe Analytics). This ensures you own all your user data and remain compliant with privacy regulations like GDPR. A simple CNAME redirect would show the Airalo White Label Storefront's URL in the browser's address bar after the page loads, breaking the seamless brand experience. The reverse proxy is the essential component that "masks" the origin URL, keeping your domain visible at all times. This is critical for brand trust, SEO, and gives you the control over caching, security, and analytics outlined in this document. ## Validation checklist Before reaching out to Airalo for support, run through these quick self-checks to confirm the integration is behaving as expected: - ✅ **Proxy resolves** — `https://airgsm.com` loads the storefront without errors. - ✅ **Domain stays masked** — the browser address bar shows your domain throughout the journey (browsing, checkout, account), never the Airalo origin URL. - ✅ **Origin is shielded** — visiting the raw Airalo origin URL directly (from an IP that is *not* whitelisted) is blocked. - ✅ **Email arrives from your domain** — a test order produces a confirmation email sent from your domain (e.g. `support@airgsm.com`), not an Airalo address. - ✅ **Forwarded headers reach the platform** — the storefront sees the correct host and the real visitor IP (confirm with Airalo if unsure). - ✅ **Analytics & consent fire** — your cookie/consent banner appears and your analytics records the visit. If any check fails, note which one before contacting Airalo — it usually points straight at the cause (header handling, whitelist drift, DNS, or email verification). ## Next steps & requirements > 🚀 To begin the integration process, Airalo requires three key pieces of information from you. 1. **Your proxy IP address** — a static, public IPv4 address (or range) of your reverse proxy server for the Airalo firewall whitelist. 2. **Email verification choice** — your choice of email verification method (full domain or single address) and the required details. 3. **Cookie and consent management script** — the JavaScript snippet for your cookie and consent management tool to ensure compliance with privacy regulations.