Authentication in REST APIs

# CHAPTER 11

Authentication in REST APIs #

1. Introduction #

2. Learning Objectives #

• Distinguish between User Authentication and Machine Authentication.

• Understand the concept and implementation of API Keys.

• Securely generate, store, and validate long-lived API Keys.

• Compare API Keys to the OAuth 2.0 Client Credentials Flow.

• Implement rate limiting to protect public APIs.

3. Beginner-Friendly Explanation #

• Human Authentication (JWT): A customer walks in, shows their ID to the teller, gets verified, and is given a temporary visitor badge (JWT) that expires in 15 minutes.

• Machine Authentication (API Key): The bank hires an automated armored truck company to drop off cash every night at 2:00 AM. There are no tellers working at 2:00 AM. Instead, the bank gives the armored truck driver a special, permanent, heavy-duty key (An API Key). The driver simply inserts the key into the loading dock door. As long as the key is valid, the door opens.

4. What is an API Key? #

Characteristics of API Keys:

1. 1. Long-Lived: Unlike JWTs, they rarely expire automatically. They exist until the developer manually revokes them.

1. 2. Opaque: Unlike JWTs, they are not Base64 encoded JSON. They are meaningless random strings. The server MUST query the database to see which developer owns the key.

1. 3. Stateless Transmission: Like JWTs, they must be transmitted with every single HTTP request.

5. Implementing API Keys #

Database Schema:

CREATE TABLE api_keys (
    id INT PRIMARY KEY,
    user_id INT, -- The developer who owns it
    key_hash VARCHAR(255), -- NEVER store the raw key!
    created_at TIMESTAMP
);

Generation Logic (Node.js/Crypto):

const crypto = require('crypto');
const bcrypt = require('bcrypt');

// 1. Generate the raw, 32-byte API Key
const rawApiKey = crypto.randomBytes(32).toString('hex');
const prefix = "sk_live_"; // Standard prefix (like Stripe)
const finalApiKey = prefix + rawApiKey;

// 2. Hash it before saving to the database
const hashedKey = await bcrypt.hash(finalApiKey, 10);
await database.save(hashedKey);

// 3. Show it to the developer EXACTLY ONCE
console.log(`Your API Key is: ${finalApiKey}. Store it safely, you will never see it again.`);

6. Verifying API Keys (Middleware) #

async function verifyApiKey(req, res, next) {
    // 1. Extract the key from the custom header or Authorization header
    const apiKey = req.headers['x-api-key'] || req.headers.authorization?.split(' ')[1];

    if (!apiKey) {
        return res.status(401).json({ error: "Missing API Key" });
    }

    // 2. Look up the hash in the database
    // (In reality, you need an index or a clever prefixing strategy to find it fast)
    const storedHash = await database.findHashForUser(req.body.userId); 
    
    // 3. Verify mathematically
    const isValid = await bcrypt.compare(apiKey, storedHash);
    
    if (!isValid) {
        return res.status(403).json({ error: "Invalid API Key" });
    }
    
    next();
}

// Protecting the Route
app.get('/api/billing-data', verifyApiKey, (req, res) => {
    res.json({ data: "Sensitive Billing Info" });
});

7. OAuth Client Credentials Flow (Advanced) #

Instead of a single, permanent API key, the machine is given a Client ID and a Client Secret. The machine sends a POST request to an Authorization Server with these credentials. If valid, the server returns a temporary Access Token (JWT). The machine uses that temporary token to hit the API. This is significantly more secure because the actual token expires quickly, limiting the damage if it is intercepted.

8. Backend Workflow: Rate Limiting #

9. Best Practices #

• Key Prefixing: Look at Stripe's API keys (e.g., sk_live_abc123). The sk stands for Secret Key, and live means it's a production key. Prefixing your keys makes it incredibly easy for developers to distinguish between their test keys (sk_test_) and live keys, preventing accidental data destruction. Furthermore, GitHub automated scanners look for these prefixes and will alert you if you accidentally commit a live key to a public repository!

10. Common Mistakes #

• Passing Keys in the URL: Never instruct developers to pass API keys in the query string (e.g., api.com/data?api_key=secret123). URLs are logged in plain text by intermediate proxy servers, internet service providers, and browser histories. API keys must ALWAYS be transmitted securely in HTTP Headers over an HTTPS connection.

11. Exercises #

1. 1. Explain why a backend system should treat the storage of generated API Keys exactly like user passwords (i.e., using hashing algorithms). What is the security risk if they are stored in plain text?

12. Coding Challenges #

• Challenge: If you are using Express.js, research the express-rate-limit package. Write a conceptual snippet of code demonstrating how you would apply a global rate limiter of 50 requests per 15 minutes to all routes starting with /api/.

13. MCQs with Answers #

14. Interview Questions #

• Q: Compare and contrast simple API Keys with the OAuth 2.0 Client Credentials Flow for Machine-to-Machine communication. In what enterprise scenario would the OAuth flow be mandated over static API keys?

• Q: Explain why API keys must be transmitted via HTTP Headers rather than URL query parameters, and why HTTPS encryption is absolutely mandatory for endpoints accepting API keys.

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #