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: 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: ✅ 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](references/token management.md). 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

mapbox-token-security