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)
• INLINECODE1 - Read style specifications
• INLINECODE2 - Access Mapbox fonts
• INLINECODE3 - Read dataset data
• INLINECODE4 - 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
• INLINECODE6 - List all styles
• INLINECODE7 - View token information
• INLINECODE8 - 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:

CODEBLOCK0

✅ Good:

CODEBLOCK1

Scope Combinations by Use Case

Public Map Display (client-side):

CODEBLOCK2

Style Management (server-side):

CODEBLOCK3

Token Administration (server-side):

CODEBLOCK4

Read-Only Access:

CODEBLOCK5

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:

CODEBLOCK6

❌ Avoid these:

CODEBLOCK7

Multiple Environment Strategy

Create separate tokens for each environment:

CODEBLOCK8

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:

CODEBLOCK9

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:

CODEBLOCK10

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