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:

// 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'];
}