Securing Maps API Keys Across Web, Mobile, and Backend Applications

5. Perimeter 2: Securing Mobile Native Applications (iOS & Android)

Mobile native applications do not execute inside a web browser and therefore do not automatically attach browser Referer headers. However, client-side mobile apps can easily be reverse-engineered.

Enforcing the `T-BUNDLE-ID` Header

Mapvina provides native mobile security enforcement through the T-BUNDLE-ID custom header:

1. In the Mapvina Portal, configure the authorized Bundle ID / Package Name (e.g., vn.yourcompany.rider).
2. In your mobile application’s network layer (Retrofit, Alamofire, or Mapvina Mobile SDK), inject the custom header into every outgoing HTTP request:
   “http
GET /route/v1/moto/105.85,21.02;105.78,21.03?key=pk_live_•••••••• HTTP/2
Host: maps.mapvina.com
T-BUNDLE-ID: vn.yourcompany.rider
“

1. Mapvina’s edge gateway validates that the incoming T-BUNDLE-ID matches the token’s configured restriction. Any script or external tool calling the endpoint without this matching header is blocked immediately with 403 Forbidden.

Defense in Depth for Mobile

For enterprise-grade mobile deployments:
Certificate Pinning: Pin Mapvina’s TLS certificate in your mobile app to prevent adversaries from intercepting network traffic using local proxy tools (such as Charles Proxy or mitmproxy).
Native App Attestation: On Android, leverage Google Play Integrity API; on iOS, use DeviceCheck / App Attest to verify that requests originate from legitimate, non-tampered binary packages.

6. Perimeter 3: Backend-for-Frontend (BFF) Proxy Architecture

While public vector map tiles must be fetched directly by client viewports, sensitive analytical APIs—such as Geocoding (converting raw addresses to coordinates), Directions (Turn-by-Turn routing), and Distance Matrix (multi-stop cost matrices)—should never be called directly from client browsers.

The BFF Architecture Flow

Instead of giving client devices direct access to high-value APIs, route requests through a lightweight Backend-for-Frontend (BFF) Reverse Proxy:

[ Client Browser / Mobile App ]
             │
             │ (1) GET /api/search?q=Hoan+Kiem (No API Key)
             ▼
[ Enterprise BFF Proxy (Node.js / Go) ]
   ├── (2) Verify User JWT Session
   ├── (3) Apply Rate Limiting (e.g. 60 req/min)
   ├── (4) Check In-Memory Cache (0ms hit!)
   └── (5) Attach PRIVATE_API_KEY from Vault / ENV
             │
             │ (6) Secure Forward over TLS
             ▼
[ Mapvina Production API Gateway ]

Key Architectural Benefits:

1. Total Credential Concealment: The private API key lives solely in your server’s environment variables. It is never transmitted across public networks or stored in client memory.
2. Strict Quota Control & Throttling: You control exactly how many requests an individual authenticated user or IP address can fire per minute, neutralizing scraping attempts.
3. Local Response Caching: Common address searches (such as “Hanoi Opera House”) and popular logistics corridors can be cached in Redis or RAM. Subsequent queries return in under 2 milliseconds while consuming 0 API quota.

Complete Zero-Dependency Node.js BFF Proxy Implementation

Below is a production-tested, zero-dependency Node.js reverse proxy demonstrating rate limiting, in-memory caching, and private key encapsulation:

/**
 * production-mapvina-bff-proxy.js
 * Zero-dependency Node.js BFF Proxy with In-Memory Caching & Rate Limiting
 */
const http = require('http');
const https = require('https');
const url = require('url');

const PORT = process.env.PORT || 8080;
// Private key loaded securely from server environment - NEVER exposed to clients
const MAPVINA_PRIVATE_KEY = process.env.MAPVINA_PRIVATE_KEY || 'sk_live_••••••••';
const MAPVINA_API_HOST = 'maps.mapvina.com';

// In-Memory Cache: Stores query responses for 10 minutes (600,000 ms)
const responseCache = new Map();
const CACHE_TTL_MS = 10 * 60 * 1000;

// Rate Limiting: Max 60 requests per minute per client IP
const rateLimitMap = new Map();
const RATE_LIMIT_WINDOW_MS = 60 * 1000;
const MAX_REQUESTS_PER_WINDOW = 60;

function isRateLimited(clientIp) {
  const now = Date.now();
  const record = rateLimitMap.get(clientIp) || { count: 0, resetTime: now + RATE_LIMIT_WINDOW_MS };

  if (now > record.resetTime) {
    record.count = 1;
    record.resetTime = now + RATE_LIMIT_WINDOW_MS;
    rateLimitMap.set(clientIp, record);
    return false;
  }

  record.count++;
  rateLimitMap.set(clientIp, record);
  return record.count > MAX_REQUESTS_PER_WINDOW;
}

const server = http.createServer((req, res) => {
  const parsedUrl = url.parse(req.url, true);
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;

  // CORS Headers
  res.setHeader('Access-Control-Allow-Origin', 'https://app.yourcompany.vn');
  res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');

  if (req.method === 'OPTIONS') {
    res.writeHead(204);
    res.end();
    return;
  }

  // 1. Healthcheck Endpoint
  if (parsedUrl.pathname === '/healthz') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'ok', timestamp: Date.now() }));
    return;
  }

  // 2. Address Geocoding / Search Proxy Endpoint
  if (parsedUrl.pathname === '/api/v1/search') {
    // Check Rate Limiting
    if (isRateLimited(clientIp)) {
      res.writeHead(429, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Too Many Requests', message: 'Rate limit exceeded. Try again later.' }));
      return;
    }

    const searchQuery = parsedUrl.query.text;
    if (!searchQuery) {
      res.writeHead(400, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Bad Request', message: 'Parameter "text" is required.' }));
      return;
    }

    // Check In-Memory Cache
    const cacheKey = `search:${searchQuery.toLowerCase().trim()}`;
    const cachedItem = responseCache.get(cacheKey);
    if (cachedItem && Date.now() < cachedItem.expiresAt) {
      res.writeHead(200, {
        'Content-Type': 'application/json',
        'X-Cache-Status': 'HIT',
        'X-Response-Time': '1ms'
      });
      res.end(cachedItem.data);
      return;
    }

    // Forward Request to Mapvina Core API with Private Key
    const targetPath = `/api/v1/search/text?text=${encodeURIComponent(searchQuery)}&size=5&key=${MAPVINA_PRIVATE_KEY}`;
    const options = {
      hostname: MAPVINA_API_HOST,
      port: 443,
      path: targetPath,
      method: 'GET',
      headers: {
        'User-Agent': 'Enterprise-BFF-Proxy/1.0',
        'Accept': 'application/json'
      }
    };

    const proxyReq = https.request(options, (proxyRes) => {
      let body = '';
      proxyRes.on('data', chunk => { body += chunk; });
      proxyRes.on('end', () => {
        if (proxyRes.statusCode === 200) {
          // Store in Cache
          responseCache.set(cacheKey, {
            data: body,
            expiresAt: Date.now() + CACHE_TTL_MS
          });
        }

        res.writeHead(proxyRes.statusCode, {
          'Content-Type': 'application/json',
          'X-Cache-Status': 'MISS'
        });
        res.end(body);
      });
    });

    proxyReq.on('error', (err) => {
      res.writeHead(502, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Bad Gateway', message: 'Failed to contact Mapvina API' }));
    });

    proxyReq.end();
    return;
  }

  res.writeHead(404, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ error: 'Not Found' }));
});

server.listen(PORT, () => {
  console.log(`BFF Security Proxy listening on port ${PORT}`);
});

7. Perimeter 4: Governance & Key Rotation on Mapvina Portal

The final perimeter is operational governance. Even with strict whitelists and proxy layers, engineering teams need tools to monitor traffic patterns, enforce quota ceilings, and respond instantly if an incident occurs.

1. Daily Quota Clamping (Hard Stop Protection)

Mapvina’s portal provides fine-grained quota caps per token. Setting a daily ceiling (e.g., 50,000 requests/day) guarantees that even if a rogue script attempts to flood your endpoint, the gateway clamps the token at the ceiling, preventing runaway billing surprises.

2. Micro-Scoping Service Permissions

Never issue a “god key” that has access to every API feature. On Mapvina Portal, configure separate tokens for separate responsibilities:
Token A (Web Client): Enabled strictly for Tiles and Styles with Domain Whitelisting.
Token B (Logistics BFF Proxy): Enabled strictly for Directions and Distance Matrix with IP Whitelisting.
* Token C (CRM & Checkout): Enabled strictly for Search / Geocoding.

If Token A is somehow compromised, an attacker cannot use it to generate expensive routing matrices or scrape customer addresses.

3. Zero-Downtime Key Rotation

When an employee leaves the company or a repository is inadvertently made public, rotate credentials immediately:
1. Navigate to https://account.mapvina.com/tokens.
2. Click the Rotate Key button next to the affected token.
3. Mapvina provides a dual-validation grace window: both the old and new key remain temporarily valid while you deploy the updated configuration to production servers.
4. Once deployment is verified, deactivate the legacy key with a single click.

8. Download the Maps API Security Quickstart Kit

To help development teams test rate limiting, benchmark proxy caching, and inspect token headers locally, Mapvina provides an open-source security quickstart repository:

9. Conclusion

Securing digital map infrastructure requires shifting from the naive hope of “hiding keys in client code” to a disciplined Defense-in-Depth Architecture:

1. Restrict all client-facing public map tokens with Domain Whitelists and Wildcard Scoping.
2. Enforce custom header validation (T-BUNDLE-ID) and certificate pinning for native mobile applications.
3. Isolate private analytical endpoints behind a Backend-for-Frontend (BFF) Proxy to achieve 100% credential confidentiality, client-side rate limiting, and 0ms in-memory response caching.
4. Actively manage token lifecycles through Daily Quota Clamping, service-level micro-scoping, and zero-downtime key rotation on the Mapvina Portal.

By implementing these four perimeters, your engineering organization can confidently deploy high-performance mapping solutions across web and mobile without exposing your infrastructure to runaway costs or unauthorized data harvesting.