How to Secure Your UPCS API Key

A UPCS API key, which starts with upcs_, authorises requests made on your account and counts against your hourly limit. Treat it like a password: it belongs on your server and nowhere else.

Keep it server-side

The embed flow is designed so the key never reaches a browser. Your server calls the session endpoint with x-api-key, then gives the page a short-lived session_token. If you find yourself pasting a key into JavaScript, an HTML template, a mobile app bundle or a public repository, stop and add a small server endpoint instead. See embedding the map on a website.

Load it from the environment

# .env (not committed)
UPCS_API_KEY=upcs_xxxxxxxxxxxxxxxx

const key = process.env.UPCS_API_KEY;
if (!key) throw new Error('UPCS_API_KEY is not set');

Add .env to your ignore file. In production use your host's secret store or a secrets manager rather than files.

Use the restrictions UPCS provides

• Register only the allowed origins you actually use.
• A key can have an IP allow-list; when one is set, a request from another IP receives a 403.
• Use a separate key per environment so a development leak does not threaten production.

Avoid accidental exposure

• Do not log request headers in full; mask the x-api-key value.
• Do not send the key in query strings, which end up in access logs.
• Scrub the key from error reports and screenshots.
• Keep it out of CI output.

If a key leaks

1. Disable the key in the partner panel. Embed sessions that depend on a disabled key stop immediately, and direct API calls with it return 401.
2. Create a new key and deploy it.
3. Review usage in your own logs; see monitoring and logging API usage.

Plan routine changes too; see API key rotation best practices.