Securing Your Integration

This guide covers security best practices for integrating Stadia Maps into your applications. Whether you're building a web app, mobile app, or server-side service, you'll find guidance here on keeping your integration secure.

How we think about security

Every API provider that offers client-side solutions faces a fundamental challenge: any credentials accessible to end users can potentially be extracted and misused. This isn't unique to Stadia Maps; it's inherent to how the client-side internet works.

Our approach focuses on:

1. Making legitimate use easy with domain-based authentication for web apps and straightforward API keys for everything else
2. Detecting and blocking abuse through monitoring systems that identify unusual patterns
3. Partnering with you to resolve issues quickly when they arise

We've designed our authentication methods to balance security with developer experience. The sections below explain how each method works and when to use it.

Why domain-based authentication is secure

For browser-based applications, we strongly recommend domain-based authentication over API keys.

Here's why it works:

When a browser makes a request to our servers, it automatically includes Origin and Referer headers identifying where the request originated. These headers are controlled by the browser itself, so JavaScript running on a page cannot forge them. This is a fundamental browser security feature, not something we invented.

This means:

• No credentials to steal. There's no API key in your source code, network requests, or app bundle for anyone to extract.
• Abuse doesn't scale. While a determined individual could make requests using tools outside a browser, they can't make thousands of browsers on other people's computers send forged headers. Browsers simply don't allow it.
• Automatic protection. You don't need to write any code to secure your credentials.

The trade-off is that domain auth only works for browser-based applications. Mobile apps, server-side code, and desktop applications need API keys.

Mobile and desktop app best practices

Apps present a unique challenge: they run on devices you don't control, and determined users can extract nearly anything from an app binary. Here's how to minimize risk:

Keep API keys out of your binary

The most common mistake is hardcoding an API key directly in your source code. This makes it trivial to extract using basic reverse engineering tools.

Better approaches include:

• On-demand resources (iOS): Store your API key in an on-demand resource that's downloaded separately from the main app bundle. This won't stop every possible attack, but it raises the bar significantly.
• Server-side key retrieval: Have your app request the API key from your own server after authenticating the user. This lets you revoke access for specific users or devices if needed.

Verify app and device integrity

Before sending an API key to your app, make sure that it's really your app. Vendor APIs like Apple's DeviceCheck and Google's Play Integrity provide a way for your server to detect many kinds of forged and abusive requests.

Use platform-secure storage

Once your app has an API key, store it using the platform's secure storage mechanisms:

• iOS: Use the Keychain Services API. Data stored here is encrypted and protected by the device's Secure Enclave.
• Android: Use the Android Keystore system. Similar to iOS Keychain, this provides hardware-backed security on supported devices.

Never store API keys in plain text files, UserDefaults/SharedPreferences, or other unencrypted locations.

Consider your threat model

Ask yourself: what's the realistic risk if someone extracts your API key?

• They'd need your key AND significant traffic to meaningfully impact your bill. Our abuse detection systems flag unusual usage patterns.
• You can revoke and rotate keys at any time through the dashboard or Account Management API.
• We're here to help if you notice unexpected usage. Contact support@stadiamaps.com.

The goal isn't perfect security (which is impossible for client-side applications), but rather making abuse impractical and recoverable.

Server-side best practices

Server-side integrations are inherently more secure because your API key never leaves infrastructure you control. Still, follow these practices:

Use environment variables

Never commit API keys to source control. Instead:

# Set in your environment
export STADIA_MAPS_API_KEY="your-api-key-here"

# Access in your code
import os
api_key = os.environ["STADIA_MAPS_API_KEY"]

Most deployment platforms (Heroku, AWS, Vercel, etc.) provide secure ways to inject environment variables at runtime.

Use the Authorization header

When making server-side requests, prefer the Authorization header over query string parameters:

Authorization: Stadia-Auth YOUR-API-KEY

This keeps your API key out of server logs, browser history, and other places where URLs might be recorded.

Rotate keys periodically

Establish a key rotation schedule appropriate for your risk tolerance. You can manage keys through:

• The client dashboard for manual rotation
• The Account Management API for automated rotation (available on request)

When rotating, create a new key before revoking the old one to avoid service interruption.

Why proxying and caching are not permitted

We sometimes hear from developers who want to proxy requests through their own servers to hide their API key from end users. While we understand the motivation, proxying and caching our services is prohibited under our Terms of Service except in specific circumstances.

Why we have this policy

Proxying creates problems that outweigh the perceived security benefits:

1. It doesn't actually improve security. You've just moved the authentication problem. Now you need to secure your proxy endpoint instead of your API key. Bad actors who would abuse your API key can just as easily abuse your proxy.

2. It inhibits our ability to help you. When requests come through a proxy, we can't distinguish between your legitimate traffic and potential abuse. If someone exploits your proxy, we may need to disable your entire account to protect our infrastructure and other customers.

3. It degrades performance. Centralizing all requests through a single proxy location adds latency for users who aren't near that location. Our global infrastructure is designed to serve users from the nearest edge; proxying defeats this.

4. It is fragile. When we make infrastructure changes, we need to notify affected customers. We can't do this effectively if we don't know how our service is being accessed, so unauthorized proxying is likely to break unexpectedly.

What to do instead

For web applications, use domain-based authentication. It's more secure than proxying and requires no infrastructure on your end.

For mobile and native apps, follow the best practices above. Yes, a determined attacker could extract your API key—but they can often exploit your proxy far more easily. With an API key you maintain full visibility and control.

For server-side applications, your API key is already hidden from end users. Make requests directly to our APIs, and secure your server per the usual best practices.

If you have a use case that genuinely requires special arrangements, contact us to discuss options. We're happy to work with customers on enterprise agreements that address specific architectural needs.

Monitoring your usage

Regularly review your usage in the client dashboard to understand your traffic patterns and catch anomalies early.

What to look for

• Unexpected spikes in request volume
• Unusual patterns in which APIs are being called

If you suspect abuse

If you notice usage that doesn't match your expectations, contact us at support@stadiamaps.com. Include:

• Your property name or ID
• The time range of suspicious activity
• What you expected vs. what you observed

We'll investigate and work with you to resolve the issue. Our goal is to make sure you're only paying for legitimate usage.

Summary

Environment	Recommended approach
Browser-based web apps	Domain-based authentication
Mobile apps (iOS/Android)	API key with secure storage (Keychain/Keystore)
Server-side applications	API key via environment variable and Authorization header
Desktop applications	API key with platform-appropriate secure storage

The right security approach depends on your specific situation. When in doubt, reach out—we're happy to discuss your architecture and recommend the best path forward.