Mapbox Token Security

Mapbox Token Security Skill

This skill provides security expertise for managing Mapbox access tokens safely and effectively.

Token Types and When to Use Them

Public Tokens (pk.\*)

Characteristics:

• Can be safely exposed in client-side code
• Limited to specific public scopes only
• Can have URL restrictions
• Cannot access sensitive APIs

When to use:

• Client-side web applications
• Mobile apps
• Public-facing demos
• Embedded maps on websites

Allowed scopes:

• styles:tiles - Display style tiles (raster)
• styles:read - Read style specifications
• fonts:read - Access Mapbox fonts
• datasets:read - Read dataset data
• vision:read - Vision API access

Secret Tokens (sk.\*)

Characteristics:

• NEVER expose in client-side code
• Full API access with any scopes
• Server-side use only
• Can create/manage other tokens

When to use:

• Server-side applications
• Backend services
• CI/CD pipelines
• Administrative tasks
• Token management

Common scopes:

• styles:write - Create/modify styles
• styles:list - List all styles
• tokens:read - View token information
• tokens:write - Create/modify tokens
• User feedback management scopes

Temporary Tokens (tk.\*)

Characteristics:

• Short-lived (max 1 hour)
• Created by secret tokens
• Single-purpose use
• Automatically expire

When to use:

• One-time operations
• Temporary delegated access
• Short-lived demos
• Security-conscious workflows

Scope Management Best Practices

Principle of Least Privilege

Always grant the minimum scopes needed:

❌ Bad:

// Overly permissive - don't do this
{
  scopes: ['styles:read', 'styles:write', 'styles:list', 'styles:delete', 'tokens:read', 'tokens:write'];
}

✅ Good:

// Only what's needed for displaying a map
{
  scopes: ['styles:read', 'fonts:read'];
}
// Add 'styles:tiles' if your map uses raster tile sources
{
  scopes: ['styles:read', 'fonts:read', 'styles:tiles'];
}

Scope Combinations by Use Case

Public Map Display (client-side):

{
  "scopes": ["styles:read", "fonts:read", "styles:tiles"],
  "note": "Public token for map display",
  "allowedUrls": ["https://myapp.com/*"]
}

Style Management (server-side):

{
  "scopes": ["styles:read", "styles:write", "styles:list"],
  "note": "Backend style management - SECRET TOKEN"
}

Token Administration (server-side):

{
  "scopes": ["tokens:read", "tokens:write"],
  "note": "Token management only - SECRET TOKEN"
}

Read-Only Access:

{
  "scopes": ["styles:list", "styles:read", "tokens:read"],
  "note": "Auditing/monitoring - SECRET TOKEN"
}

URL Restrictions

Why URL Restrictions Matter

URL restrictions limit where a public token can be used, preventing unauthorized usage if the token is exposed.

Effective URL Patterns

✅ Recommended patterns:

https://myapp.com/*           # Production domain
https://*.myapp.com/*         # All subdomains
https://staging.myapp.com/*   # Staging environment
http://localhost:*            # Local development

❌ Avoid these:

*                             # No restriction (insecure)
http://*                      # Any HTTP site (insecure)
*.com/*                       # Too broad

Multiple Environment Strategy

Create separate tokens for each environment:

// Production
{
  note: "Production - myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://myapp.com/*", "https://www.myapp.com/*"]
}

// Staging
{
  note: "Staging - staging.myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://staging.myapp.com/*"]
}

// Development
{
  note: "Development - localhost",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["http://localhost:*", "http://127.0.0.1:*"]
}

Token Storage and Handling

Server-Side (Secret Tokens)

✅ DO:

• Store in environment variables
• Use secret management services (AWS Secrets Manager, HashiCorp Vault)
• Encrypt at rest
• Limit access via IAM policies
• Log token usage

❌ DON'T:

• Hardcode in source code
• Commit to version control
• Store in plaintext configuration files
• Share via email or Slack
• Reuse across multiple services

Example: Secure Environment Variable:

# .env (NEVER commit this file)
MAPBOX_SECRET_TOKEN=sk.ey...

# .gitignore (ALWAYS include .env)
.env
.env.local
.env.*.local

Client-Side (Public Tokens)

✅ DO:

• Use public tokens only
• Apply URL restrictions
• Use different tokens per app
• Rotate periodically
• Monitor usage

❌ DON'T:

• Expose secret tokens
• Use tokens without URL restrictions
• Share tokens between unrelated apps
• Use tokens with excessive scopes

Example: Safe Client Usage:

// Public token with URL restrictions - SAFE
const mapboxToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';

// This token is restricted to your domain
// and only has styles:read scope
mapboxgl.accessToken = mapboxToken;

Security Checklist

Token Creation:

• [ ] Use public tokens for client-side, secret for server-side
• [ ] Apply principle of least privilege for scopes
• [ ] Add URL restrictions to public tokens
• [ ] Use descriptive names/notes for token identification
• [ ] Document intended use and environment

Token Management:

• [ ] Store secret tokens in environment variables or secret managers
• [ ] Never commit tokens to version control
• [ ] Rotate tokens every 90 days (or per policy)
• [ ] Remove unused tokens promptly
• [ ] Separate tokens by environment (dev/staging/prod)

Monitoring:

• [ ] Track token usage patterns
• [ ] Set up alerts for unusual activity
• [ ] Regular security audits (monthly)
• [ ] Review team access quarterly
• [ ] Scan repositories for exposed tokens

Incident Response:

• [ ] Documented revocation procedure
• [ ] Emergency contact list
• [ ] Rotation process documented
• [ ] Post-incident review template
• [ ] Team training on security procedures

Reference Files

For detailed guidance on specific topics, load these references as needed:

• `references/rotation-monitoring.md` — Token rotation strategies (zero-downtime + emergency), monitoring metrics, alerting rules, and monthly/quarterly audit checklists. Load when: implementing rotation, setting up monitoring, or conducting audits.
• `references/incident-response.md` — Step-by-step incident response plan and common security mistakes with code examples. Load when: responding to a token compromise, reviewing code for security issues, or training on anti-patterns.

When to Use This Skill

Invoke this skill when:

• Creating new tokens
• Deciding between public vs secret tokens
• Setting up token restrictions
• Implementing token rotation
• Investigating security incidents
• Conducting security audits
• Training team on token security
• Reviewing code for token exposure

Mapbox Token Security Guide

Quick reference for securing Mapbox access tokens. Critical security rules for token management.

Token Types - Quick Reference

Critical Security Rules

❌ Never Do This

// ❌ NEVER commit tokens
const MAPBOX_TOKEN = 'pk.eyJ1...'; // Don't hardcode!

// ❌ NEVER use secret tokens client-side
<script>mapboxgl.accessToken = 'sk.eyJ1...'; // Exposed to users!</script>;

// ❌ NEVER log tokens
console.log('Token:', token); // Shows in browser console

// ❌ NEVER share tokens in public repos
// .env file committed to GitHub

✅ Always Do This

// ✅ Use environment variables
const MAPBOX_TOKEN = process.env.NEXT_PUBLIC_MAPBOX_TOKEN;

// ✅ Add URL restrictions to public tokens
// In Mapbox dashboard: Restrict to your domain(s)

// ✅ Use secret tokens only server-side
// server.js or API routes only

// ✅ Add .env to .gitignore
// .gitignore
.env
.env.local

Token Selection Decision Tree

Question 1: Where will this token be used?

• Client-side (browser/mobile) → Use public token (pk.\*)
• Server-side (API/backend) → Use secret token (sk.\*)
• One-time operation → Use temporary token (tk.\*)

Question 2: What operations are needed?

• Display maps only → Public token with styles:tiles, styles:read
• Upload/modify data → Secret token with write scopes
• Administrative tasks → Secret token with admin scopes

Scope Management

Public Token Scopes (Most Common)

✅ styles:tiles    - Display raster style tiles
✅ styles:read     - Read style specifications
✅ fonts:read      - Access Mapbox fonts
✅ datasets:read   - Read dataset data

Secret Token Scopes (Server-Side Only)

⚠️  styles:write   - Create/modify styles
⚠️  styles:list    - List all styles
⚠️  tokens:write   - Create/modify tokens
⚠️  uploads:write  - Upload data

Principle: Grant minimum scopes needed. Don't use styles:write if only reading.

URL Restrictions

For all public tokens, always add URL restrictions:

1. Go to Mapbox Dashboard → Access Tokens 2. Select token → URL Restrictions 3. Add allowed URLs:

   http://localhost:*          # Development
   https://yourdomain.com/*    # Production
   https://*.yourdomain.com/*  # Subdomains

Impact: Prevents token abuse if exposed. Must do for production.

Environment Variable Setup

Web Applications

# .env.local (Next.js, Vite)
NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_token_here
VITE_MAPBOX_TOKEN=pk.your_token_here

# .env (Create React App)
REACT_APP_MAPBOX_TOKEN=pk.your_token_here

Mobile Applications

// iOS (Config.xcconfig)
MAPBOX_TOKEN = pk.your_token_here;

// Android (gradle.properties)
MAPBOX_TOKEN = pk.your_token_here;

Always add to .gitignore:

.env
.env.local
.env.*.local

Token Rotation

When to rotate:

• 🔴 Immediately if token exposed publicly (GitHub, logs, etc.)
• 🟡 Every 90 days for secret tokens (best practice)
• 🟡 When team member leaves with access
• 🟡 After security incident

How to rotate safely:

1. Create new token with same scopes 2. Update environment variables 3. Deploy new code 4. Verify new token works 5. Delete old token (grace period: 24-48hrs)

Common Vulnerabilities

1. Token in Public Repository

Risk: Anyone can use your token, rack up charges Fix: Immediately rotate token, add to .gitignore, use git history rewrite if needed

2. No URL Restrictions

Risk: Token can be used on any domain Fix: Add URL restrictions in dashboard immediately

3. Secret Token in Frontend

Risk: Full API access exposed to all users Fix: Move to server-side, rotate token immediately

4. Overly Permissive Scopes

Risk: Token can do more than needed Fix: Create new token with minimum required scopes

Token Exposure Response

If token is exposed publicly:

1. Immediately create new token in dashboard 2. Update environment variables with new token 3. Deploy updated code 4. Delete exposed token in dashboard 5. Check Mapbox dashboard for unexpected usage 6. Add URL restrictions to new token 7. Review security practices

Don't wait - exposed tokens can be used within minutes.

Quick Security Checklist

✅ Using public tokens (pk._) for client-side? ✅ URL restrictions added to all public tokens? ✅ No tokens hardcoded in source code? ✅ .env files in .gitignore? ✅ Secret tokens (sk._) only used server-side? ✅ Minimum scopes granted per token? ✅ Tokens rotated regularly (90 days)? ✅ No tokens in logs or console output? ✅ Different tokens for dev/staging/production? ✅ Team members have individual tokens (not shared)?

Framework-Specific Patterns

Next.js

// Public token (client-side)
const token = process.env.NEXT_PUBLIC_MAPBOX_TOKEN;

// Secret token (server-side API routes only)
const secretToken = process.env.MAPBOX_SECRET_TOKEN;

React

// Must use REACT_APP_ prefix
const token = process.env.REACT_APP_MAPBOX_TOKEN;

Vue/Vite

// Must use VITE_ prefix
const token = import.meta.env.VITE_MAPBOX_TOKEN;

Rate Limiting

Free tier limits:

• 50,000 map loads/month
• 100,000 API requests/month

Best practices:

• Cache tiles in CDN
• Implement client-side caching
• Monitor usage in dashboard
• Set up usage alerts

If approaching limits: Upgrade plan or optimize caching.

Incident Response & Common Mistakes

Incident Response Plan

If a Token is Compromised

Immediate actions (first 15 minutes):

1. Revoke the token via Mapbox dashboard or API 2. Create replacement token with different scopes/restrictions if needed 3. Update all services using the compromised token 4. Notify team via incident channel

Investigation (within 24 hours): 5. Review access logs to understand exposure 6. Check for unauthorized usage in Mapbox dashboard 7. Identify root cause (how was it exposed?) 8. Document incident with timeline and impact

Prevention (within 1 week): 9. Update procedures to prevent recurrence 10. Implement additional safeguards (CI checks, secret scanning) 11. Train team on lessons learned 12. Update documentation with new security measures

Common Security Mistakes

1. Exposing Secret Tokens in Client Code

❌ CRITICAL ERROR:

// NEVER DO THIS - Secret token in client code
const map = new mapboxgl.Map({
  accessToken: 'sk.YOUR_SECRET_TOKEN_HERE' // SECRET TOKEN
});

✅ Correct:

// Public token only in client code
const map = new mapboxgl.Map({
  accessToken: 'pk.YOUR_PUBLIC_TOKEN_HERE' // PUBLIC TOKEN
});

2. Overly Permissive Scopes

❌ Too broad:

{
  "scopes": ["styles:*", "tokens:*"]
}

✅ Specific:

{
  "scopes": ["styles:read"]
}

3. Missing URL Restrictions

❌ No restrictions:

{
  "scopes": ["styles:read"],
  "allowedUrls": [] // Token works anywhere
}

✅ Domain restricted:

{
  "scopes": ["styles:read"],
  "allowedUrls": ["https://myapp.com/*"]
}

4. Long-Lived Tokens Without Rotation

❌ Never rotated:

Token created: Jan 2020
Last rotation: Never
Still in production: Yes

✅ Regular rotation:

Token created: Dec 2024
Last rotation: Dec 2024
Next rotation: Mar 2025

5. Tokens in Version Control

❌ Committed to Git:

// config.js (committed to repo)
export const MAPBOX_TOKEN = 'sk.YOUR_SECRET_TOKEN_HERE';

✅ Environment variables:

// config.js
export const MAPBOX_TOKEN = process.env.MAPBOX_SECRET_TOKEN;

# .env (in .gitignore)
MAPBOX_SECRET_TOKEN=sk.YOUR_SECRET_TOKEN_HERE

Token Rotation & Monitoring

Token Rotation Strategy

When to Rotate Tokens

Mandatory rotation:

• Token exposed in public repository
• Team member leaves with token access
• Suspected compromise or breach
• Service decommissioning
• Compliance requirements

Scheduled rotation:

• Every 90 days (recommended for production)
• Every 30 days (high-security environments)
• After major deployments
• During security audits

Rotation Process

Zero-downtime rotation:

1. Create new token with same scopes 2. Deploy new token to canary/staging environment 3. Verify functionality with new token 4. Gradually roll out to production 5. Monitor for issues for 24-48 hours 6. Revoke old token after confirmation 7. Update documentation with rotation date

Emergency rotation:

1. Immediately revoke compromised token 2. Create replacement token 3. Deploy emergency update to all services 4. Notify team of incident 5. Investigate how compromise occurred 6. Update procedures to prevent recurrence

Monitoring and Auditing

Track Token Usage

Metrics to monitor:

• API request volume per token
• Geographic distribution of requests
• Error rates by token
• Unexpected spike patterns
• Requests from unauthorized domains

Alert on:

• Usage from unexpected IPs/regions
• Sudden traffic spikes (>200% normal)
• High error rates (>10%)
• Requests outside allowed URLs
• Off-hours access patterns

Regular Security Audits

Monthly checklist:

• [ ] Review all active tokens
• [ ] Verify token scopes are still appropriate
• [ ] Check for unused tokens (revoke if inactive >30 days)
• [ ] Confirm URL restrictions are current
• [ ] Review team member access
• [ ] Check for tokens in public repositories (GitHub scan)
• [ ] Verify documentation is up-to-date

Quarterly checklist:

• [ ] Rotate production tokens
• [ ] Full token inventory
• [ ] Access control review
• [ ] Update incident response procedures
• [ ] Security training for team