Apple Maps JWT Service

🔐 Secure server-side JWT generation service for Apple MapKit JS authentication

This service provides secure JWT token generation for Apple MapKit JS, solving mobile WebKit security restrictions by handling authentication server-side with proper Apple Developer credentials.

🚀 Features

• Secure Authentication: API key-based access control
• Apple MapKit JWT: Server-side token generation with ES256 signing
• CORS Support: Cross-origin requests for web applications
• Environment Security: Credentials stored as environment variables
• TTL Validation: Configurable token expiration with security limits
• Error Handling: Comprehensive error responses without data leaks

📡 API Endpoints

POST /api/token

Generate a MapKit JWT token for authentication.

Headers:

Content-Type: application/json
X-API-Key: your-api-key

Request Body:

{
  "ttl": 3600,
  "origin": "optional-domain-restriction",
  "sessionId": "optional-session-id"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJ...",
    "expiresAt": 1640995200000,
    "expiresIn": 3600,
    "restricted": false,
    "origin": null,
    "sessionId": null
  }
}

GET /api/health

Service health check endpoint.

Response:

{
  "success": true,
  "service": "Apple Maps JWT Service",
  "version": "1.0.0",
  "status": "healthy",
  "timestamp": "2025-08-18T04:30:00.000Z"
}

🔧 Setup & Deployment

1. Environment Variables

Configure these in your Vercel dashboard or .env.local:

Variable	Description	Required
MAPKIT_API_KEY	Secure API key for endpoint access	✅
APPLE_TEAM_ID	Your Apple Developer Team ID	✅
MAPKIT_KEY_ID	Your MapKit Key ID	✅
MAPKIT_PRIVATE_KEY	Your P8 private key content	✅

2. Deploy to Vercel

# Clone this repository
git clone https://github.com/frasergibbs/apple-maps-jwt-service.git
cd apple-maps-jwt-service

# Install dependencies
npm install

# Deploy to production
vercel --prod

3. Configure Environment Variables

# Set environment variables in Vercel
vercel env add MAPKIT_API_KEY
vercel env add APPLE_TEAM_ID
vercel env add MAPKIT_KEY_ID
vercel env add MAPKIT_PRIVATE_KEY

🔒 Security Features

API Key Authentication

Every request requires a valid X-API-Key header:

curl -X POST https://your-service.vercel.app/api/token \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secure-api-key" \
  -d '{"ttl": 3600}'

TTL Validation

• Default TTL: 1 hour (3600 seconds)
• Maximum TTL: 24 hours (86400 seconds)
• Automatic validation and capping

Environment Variable Security

• No credentials stored in code
• Secure environment variable storage
• Automatic key formatting and validation

🛠️ Local Development

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local
# Edit .env.local with your credentials

# Start development server
npm run dev

🔄 Integration

Client-Side Usage

// Generate JWT token
const response = await fetch('https://your-service.vercel.app/api/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    ttl: 3600,
    origin: 'app://obsidian.md'
  })
});

const { data } = await response.json();
const { token } = data;

// Use token with MapKit JS
mapkit.init({
  authorizationCallback: (done) => {
    done(token);
  }
});

Plugin Integration

This service is designed to work with the Apple Maps Obsidian Plugin:

// Automatic fallback in MapKit service
const response = await this.proxyService.generateToken({
  ttl: 3600,
  origin: 'app://obsidian.md'
});

📋 API Reference

Error Responses

All errors follow a consistent format:

{
  "success": false,
  "error": "Description of the error"
}

Common error codes:

• 401: Invalid or missing API key
• 405: Method not allowed
• 500: Server configuration error or token generation failure

CORS Support

All endpoints support CORS with appropriate headers:

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: GET, POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, X-API-Key

🔍 Monitoring

Health Checks

Monitor service availability:

curl https://your-service.vercel.app/api/health

Logging

The service logs errors and important events:

• Authentication failures
• Missing environment variables
• Token generation errors
• Request processing metrics

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🔗 Related Projects

• Apple Maps Obsidian Plugin - The client-side plugin
• Apple MapKit JS Documentation - Official Apple documentation

---

Made with ❤️ for secure Apple Maps integration