mapbox-token-security

SKILL.md

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