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:

Scope Combinations by Use Case

Public Map Display (client-side):

Style Management (server-side):

Token Administration (server-side):

Read-Only Access:

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:

❌ Avoid these:

Multiple Environment Strategy

Create separate tokens for each environment:

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:

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.

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:

1. Resolve the token from the env pattern for your bundler (never hardcode a real pk. in source)
2. Validate it is present and not a placeholder
3. 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.

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