Mapbox Token Security

# Mapbox Token Security Guide

Quick reference for securing Mapbox access tokens. Critical security rules for token management.

## Token Types - Quick Reference

| Type          | Format | Use                      | Can Expose?                    |
| ------------- | ------ | ------------------------ | ------------------------------ |
| **Public**    | `pk.*` | Client-side, mobile apps | ✅ Yes (with URL restrictions) |
| **Secret**    | `sk.*` | Server-side only         | ❌ NEVER expose                |
| **Temporary** | `tk.*` | One-time operations      | ✅ Yes (expires in 1hr)        |

## Critical Security Rules

### ❌ Never Do This

```javascript
// ❌ NEVER commit tokens
const MAPBOX_TOKEN = 'pk.eyJ1...'; // Don't hardcode!

// ❌ NEVER use secret tokens client-side
<script>mapboxgl.accessToken = 'sk.eyJ1...'; // Exposed to users!</script>;

// ❌ NEVER log tokens
console.log('Token:', token); // Shows in browser console

// ❌ NEVER share tokens in public repos
// .env file committed to GitHub
```

### ✅ Always Do This

```javascript
// ✅ Use environment variables
const MAPBOX_TOKEN = process.env.NEXT_PUBLIC_MAPBOX_TOKEN;

// ✅ Add URL restrictions to public tokens
// In Mapbox dashboard: Restrict to your domain(s)

// ✅ Use secret tokens only server-side
// server.js or API routes only

// ✅ Add .env to .gitignore
// .gitignore
.env
.env.local
```

## Token Selection Decision Tree

**Question 1: Where will this token be used?**

- Client-side (browser/mobile) → Use **public token** (pk.\*)
- Server-side (API/backend) → Use **secret token** (sk.\*)
- One-time operation → Use **temporary token** (tk.\*)

**Question 2: What operations are needed?**

- Display maps only → Public token with `styles:tiles, styles:read`
- Upload/modify data → Secret token with write scopes
- Administrative tasks → Secret token with admin scopes

## Scope Management

### Public Token Scopes (Most Common)

```
✅ styles:tiles    - Display raster style tiles
✅ styles:read     - Read style specifications
✅ fonts:read      - Access Mapbox fonts
✅ datasets:read   - Read dataset data
```

### Secret Token Scopes (Server-Side Only)

```
⚠️  styles:write   - Create/modify styles
⚠️  styles:list    - List all styles
⚠️  tokens:write   - Create/modify tokens
⚠️  uploads:write  - Upload data
```

**Principle:** Grant minimum scopes needed. Don't use `styles:write` if only reading.

## URL Restrictions

**For all public tokens, always add URL restrictions:**

1. Go to Mapbox Dashboard → Access Tokens
2. Select token → URL Restrictions
3. Add allowed URLs:
   ```
   http://localhost:*          # Development
   https://yourdomain.com/*    # Production
   https://*.yourdomain.com/*  # Subdomains
   ```

**Impact:** Prevents token abuse if exposed. Must do for production.

## Environment Variable Setup

### Web Applications

```bash
# .env.local (Next.js, Vite)
NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_token_here
VITE_MAPBOX_TOKEN=pk.your_token_here

# .env (Create React App)
REACT_APP_MAPBOX_TOKEN=pk.your_token_here
```

### Mobile Applications

```javascript
// iOS (Config.xcconfig)
MAPBOX_TOKEN = pk.your_token_here;

// Android (gradle.properties)
MAPBOX_TOKEN = pk.your_token_here;
```

**Always add to .gitignore:**

```
.env
.env.local
.env.*.local
```

## Token Rotation

**When to rotate:**

- 🔴 Immediately if token exposed publicly (GitHub, logs, etc.)
- 🟡 Every 90 days for secret tokens (best practice)
- 🟡 When team member leaves with access
- 🟡 After security incident

**How to rotate safely:**

1. Create new token with same scopes
2. Update environment variables
3. Deploy new code
4. Verify new token works
5. Delete old token (grace period: 24-48hrs)

## Common Vulnerabilities

### 1. Token in Public Repository

**Risk:** Anyone can use your token, rack up charges
**Fix:** Immediately rotate token, add to .gitignore, use git history rewrite if needed

### 2. No URL Restrictions

**Risk:** Token can be used on any domain
**Fix:** Add URL restrictions in dashboar