Authentication

​

Overview

​

Authentication Methods

​

Bearer Token (Firebase JWT)

​

How It Works

1. User authenticates via Firebase (email/password, OAuth, etc.)
2. Firebase returns an ID token
3. Include token in Authorization header
4. Backend verifies token with Firebase Admin SDK

​

Request Format

curl https://api.monkeytype.com/users \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

​

Token Requirements

• Valid Firebase ID token
• Token not expired (tokens expire after 1 hour)
• User account exists in Monkeytype database

​

Fresh Tokens

• User deletion
• Account reset
• Email/password updates
• Name changes
• Token revocation

// Endpoints requiring fresh tokens
requireFreshToken: true

​

Token Caching

• Email verification checks
• Token revocation
• Real-time permission updates

noCache: true  // Disable token caching

​

ApeKey Authentication

​

What Are ApeKeys?

• Long-lived authentication (no expiration)
• Higher rate limits
• Programmatic access to user data
• Fine-grained control (enable/disable per key)

​

Creating an ApeKey

1. Authenticate with Bearer token
2. POST to /ape-keys endpoint:

curl -X POST https://api.monkeytype.com/ape-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "enabled": true
  }'

{
  "message": "Ape Key generated",
  "data": {
    "apeKey": "BASE64_ENCODED_KEY",
    "apeKeyId": "507f1f77bcf86cd799439011",
    "apeKeyDetails": {
      "name": "My Integration",
      "enabled": true,
      "createdOn": 1234567890
    }
  }
}

​

Using ApeKeys

curl https://api.monkeytype.com/results \
  -H "Authorization: ApeKey YOUR_APE_KEY"

​

ApeKey Format

• Key ID (identifies the key)
• Secret (hashed using bcrypt)
• Combined and base64url-encoded

​

ApeKey Management

curl https://api.monkeytype.com/ape-keys \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X PATCH https://api.monkeytype.com/ape-keys/{apeKeyId} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "enabled": false}'

curl -X DELETE https://api.monkeytype.com/ape-keys/{apeKeyId} \
  -H "Authorization: Bearer YOUR_TOKEN"

​

ApeKey Configuration

configuration.apeKeys.acceptKeys  // false to disable globally
configuration.apeKeys.endpointsEnabled  // false to disable management endpoints

​

Endpoint Support

authenticationOptions: {
  acceptApeKeys: true  // Endpoint accepts ApeKeys
}

• GET /results
• GET /users/personalBests
• GET /users/stats
• GET /users/tags
• GET /users/streak
• GET /leaderboards/rank
• And more…

​

Public Endpoints

• GET / - API status
• GET /leaderboards - Public leaderboards
• GET /users/:name/profile - Public profiles
• GET /users/checkName/:name - Username availability
• POST /users/forgotPasswordEmail - Password reset request

# No Authorization header needed
curl https://api.monkeytype.com/leaderboards?language=english&mode=time&mode2=60

​

Authentication Flow

​

Backend Authentication Process

1. Extract Authorization Header
   const authHeader = req.headers['authorization'];
   
2. Determine Auth Scheme
   • Bearer → Verify Firebase token
   • ApeKey → Validate API key
   • Uid → Development-only mode
   • None → Public endpoint or error
3. Verify Credentials
   • Bearer: verifyIdToken() via Firebase Admin
   • ApeKey: Lookup key, verify hash with bcrypt
4. Attach Context
   req.ctx.decodedToken = {
     type: 'Bearer' | 'ApeKey' | 'None',
     uid: string,
     email: string
   }
   
5. Check Permissions
   • Verify endpoint allows auth type
   • Check user permissions (admin, quoteMod, etc.)
   • Validate configuration requirements

​

Error Handling

​

Common Authentication Errors

{
  "message": "Unauthorized"
}

{
  "message": "Token expired - please login again"
}

{
  "message": "Token revoked - please login again"
}

{
  "message": "This endpoint does not accept ApeKeys"
}

{
  "message": "ApeKey not found"
}

{
  "message": "ApeKey is disabled"
}

{
  "message": "ApeKey structure is invalid"
}

{
  "message": "ApeKeys are not being accepted at this time"
}

​

Rate Limiting by Auth Type

rateLimit: {
  normal: "resultsGet",      // Bearer token limit
  apeKey: "resultsGetApe"    // ApeKey limit (typically higher)
}

​

Bad Authentication Rate Limiting

• Limit: 30 failed attempts per hour per IP
• Triggers: Invalid tokens, wrong passwords, malformed credentials
• Result: Temporary IP ban

​

Development Mode

​

Uid Authentication (Dev Only)

curl https://api.monkeytype.com/users \
  -H "Authorization: Uid YOUR_USER_ID|[email protected]"

​

Public on Dev

authenticationOptions: {
  isPublicOnDev: true  // No auth needed in dev mode
}

​

Security Best Practices

​

Token Management

1. Never expose tokens in client code
   // Bad
   const token = 'hardcoded-token';
   
   // Good
   const token = await firebase.auth().currentUser.getIdToken();
   
2. Refresh expired tokens
   const token = await firebase.auth().currentUser.getIdToken(true);
   
3. Handle token expiration gracefully
   if (error.status === 401) {
     await refreshToken();
     retry(request);
   }
   

​

ApeKey Security

1. Store securely - Use environment variables or secret managers
2. Rotate regularly - Delete old keys, generate new ones
3. Disable unused keys - Don’t delete if you need audit trail
4. Use specific keys - Different keys for different integrations
5. Monitor usage - Check lastUsedOn timestamp

​

Request Headers

curl https://api.monkeytype.com/users \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Client-Version: 2024.12.0" \
  -H "User-Agent: YourApp/1.0"

​

Example: Complete Auth Flow

import { initializeApp } from 'firebase/app';
import { getAuth, signInWithEmailAndPassword } from 'firebase/auth';

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

// Authenticate user
const userCredential = await signInWithEmailAndPassword(
  auth,
  '[email protected]',
  'password'
);

// Get ID token
const idToken = await userCredential.user.getIdToken();

// Make API request
const response = await fetch('https://api.monkeytype.com/users', {
  headers: {
    'Authorization': `Bearer ${idToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

​

Troubleshooting

​

Token Verification Failed

1. Check token expiration (max 1 hour)
2. Verify Firebase project configuration
3. Ensure user exists in database
4. Check for token revocation

​

ApeKey Not Working

1. Verify endpoint accepts ApeKeys
2. Check ApeKey is enabled
3. Confirm system-wide ApeKeys not disabled
4. Validate ApeKey format (base64url-encoded)
5. Ensure ApeKey not deleted

​

Fresh Token Required

1. Re-authenticate user
2. Get new token with getIdToken(true)
3. Ensure token issued within last 60 seconds