Security best practices for Mapbox access tokens, including scope management, URL restrictions, rotation strategies, and protecting sensitive data. Use when creating, managing, or advising on Mapbox token security.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Security best practices for Mapbox access tokens, including scope management, URL restrictions, rotation strategies, and protecting sensitive data. Use when creating, managing, or advising on 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:
- Create/modify styles
styles:write
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/*"]}
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
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 (Vite):
Note: This example uses Vite. For Next.js, CRA, Angular, or a plain window.MAPBOX_ACCESS_TOKEN / CDN setup, see Token Management. Do not chain import.meta.env and process.env in one expression — the unused path throws ReferenceError in the browser.
// Public token with URL restrictions - SAFE (Vite)const mapboxToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
// Guard BEFORE constructing the map — missing tokens otherwise yield a silent blank mapif (!mapboxToken || mapboxToken === 'YOUR_MAPBOX_ACCESS_TOKEN') {
thrownewError('Missing VITE_MAPBOX_ACCESS_TOKEN — set it in env before creating the map');
}
mapboxgl.accessToken = mapboxToken;
Agent anti-pattern: skip the token guard
Agents often assign mapboxgl.accessToken and call new mapboxgl.Map(...) with no check. That fails closed as a blank canvas with no UI error.
Always:
Resolve the token from the env pattern for your bundler (never hardcode a real pk. in source)
Validate it is present and not a placeholder
Only then set accessToken and construct the map
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)
Guard missing tokens in client code before new mapboxgl.Map
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/token-management.md — Bundler-specific env var names and access patterns (Vite / Next / CRA / Angular / CDN). Load when: wiring tokens in a different framework than the Vite example above.
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.
