Best Practices

Follow these guidelines to keep your maps.guru integration secure in production.

API Key Security

Never Expose Keys in Client-Side Code

// BAD — key visible in browser source
const map = new maplibregl.Map({
  style: `https://maps.guru/api/v1/styles/standard/light/style.json?key=mapx_secret_key`
});

Instead, proxy through your backend:

// GOOD — key stays on your server
const map = new maplibregl.Map({
  style: '/api/map-style' // Your backend fetches with the API key
});

Use Environment Variables

# .env (never committed)
MAPS_GURU_API_KEY=mapx_your_key

// server.js
const apiKey = process.env.MAPS_GURU_API_KEY;

Separate Keys Per Environment

HTTPS Only

All maps.guru endpoints enforce HTTPS. Never use HTTP — it exposes your API key in transit.

Restrict Key Scopes

Follow the principle of least privilege:

• If an application only needs geocoding, create a key with only the geocoding scope
• If a frontend only displays maps, use a key with only the maps scope
• Never use the default all-scopes key in production

Monitor Usage

Set up monitoring to detect anomalies:

1. Check daily — Review the usage dashboard for unexpected spikes
2. Set alerts — Configure budget warnings in the admin dashboard
3. Audit keys — Regularly review which keys exist and revoke unused ones

Rotate Keys Regularly

Establish a key rotation schedule:

1. Create a new key
2. Deploy the new key to your application
3. Verify everything works
4. Revoke the old key
5. Repeat quarterly (or after any team member departure)

Incident Response

If you suspect a key has been compromised:

1. Revoke immediately — Go to Dashboard → API Keys → Revoke
2. Create a new key — Generate a replacement
3. Update applications — Deploy the new key
4. Review usage — Check for any unauthorized requests
5. Audit access — Review who had access to the compromised key

OAuth Consent Management

OAuth-authorized clients are managed separately from mapx_ keys. The platform splits them across two dashboard pages so each type is manageable at the right granularity:

• maps.guru/dashboard/settings/connected-apps — remote MCP connectors (ChatGPT, Claude) and other third-party OAuth clients. One row per client, regardless of how many machines you've approved it on.
• maps.guru/dashboard/settings/devices — individual @invarya/maps-mcp auth login installs (each machine or CLI sandbox is its own row). CLI entries are deliberately filtered out of Connected Apps to avoid clutter — revoke a specific machine here, or revoke all your CLI installs in one pass.

Revoking an OAuth Client

When you revoke an OAuth consent, the platform does three things atomically:

1. Marks every refresh token revoked for that (user, client) pair (oauth_refresh_token.revoked = NOW()). The client cannot mint a fresh access token.
2. Hard-deletes any stored access tokens for that pair. (Most access tokens are stateless JWTs — those still expire on their own within 15 minutes — but any opaque tokens are nuked instantly.)
3. Deletes the consent row. The next OAuth flow lands on the consent screen instead of being silently approved.

In practical terms: revoking an OAuth client locks them out at most 15 minutes later (the JWT TTL), with a hard guarantee that they cannot refresh. Often it's effective immediately.

Platform-wide Audit (Superadmin Only)

Superadmins (user.role === 'admin') get a global view at maps.guru/dashboard/settings/admin/oauth-consents — every consent across every user. Useful for:

• Spotting an OAuth client that suddenly has thousands of grants (potential abuse signal)
• Force-revoking a misbehaving client across all users in one click
• Verifying which orgs have authorized which AI integrations

Search by user email/name or client name; filter by clientId.

When to Revoke vs Rotate

mapx_ keys (long-lived bearers used for tiles, geocoding, embeds) and OAuth consents (short-lived JWTs used by MCP) live on separate tracks. Revoking one doesn't affect the other.