API Key

Definition

When you sign up for a weather API, maps service, or payment processor, they give you a long string of random characters like “YOUR-API-KEY-HERE-xxxxxxxxxxxxx”. That’s your API key. It’s essentially a password for your application - a unique identifier that tells the API “this request is coming from a legitimate, registered user.”

API keys serve multiple purposes beyond just identification. They let API providers track how much you’re using their service (important for billing and rate limiting), understand usage patterns across their customer base, and quickly shut down access if someone misuses their API. If your key is compromised or you stop paying, they can simply revoke that key without affecting any other customers.

Here’s an important distinction that trips people up: API keys identify your application, not your users. They’re meant for scenarios like “this request is from Company XYZ’s weather app” rather than “this request is from John Smith.” For user authentication (proving that John Smith is who he says he is), you need something like OAuth or JWT. API keys are simpler but less powerful - they’re the lock on the front door of a building, not the individual keycards for each apartment.

Example

Google Maps Integration: When you embed Google Maps in your website, you include an API key that Google gave you. Every time someone loads your map, that key is sent to Google. Google uses it to track your usage, ensure you’re within your quota, and charge you if you exceed free limits. If someone steals your key and racks up charges, you can revoke it and get a new one.

Weather Data Service: A weather app might use OpenWeatherMap’s API. The developer gets a key during signup, includes it in requests like GET /weather?city=NYC&apiKey=abc123, and OpenWeatherMap tracks how many requests that key makes. Free tier allows 1000 requests/day; going over requires a paid plan.

Payment Processing: Stripe gives you two keys - a test key (pk_test_XXXXX…) and a live key (pk_live_XXXXX…). The prefixes make it obvious which is which. You use the test key during development so you don’t accidentally charge real credit cards, then switch to the live key in production.

Email Delivery: SendGrid provides API keys for sending emails programmatically. Different keys can have different permissions - one might only send emails while another can also manage templates and view analytics. If a key is compromised, you revoke just that key.

Internal Microservices: Even within a company, services might use API keys to identify themselves to each other. The billing service knows that requests with key “svc_inventory_prod” are from the inventory service and can trust them accordingly.

Analogy

The Library Card: An API key is like a library card. It identifies you as a registered member and lets you borrow books (access API resources). The library tracks what you borrow using your card number, limits how many books you can have at once (rate limiting), and can revoke your card if you don’t return books. But the card itself doesn’t prove you’re you - anyone who finds your card could use it.

The Gym Membership Tag: When you scan your keytag at the gym, it identifies your membership - letting you in, tracking your visits, and verifying you’ve paid. The gym doesn’t check your ID every time; they trust the tag. But if someone steals your tag, they can get in too. That’s why API keys need to be kept secure.

The Corporate Building Badge: Your work badge gets you into the building and specific floors. The security system logs when you enter and exit. If you lose your badge, you get it deactivated and get a new one. The badge identifies you to the building system, but it’s not the same as checking your ID at the door.

The Parking Pass: A parking garage might give you a card or sticker that identifies you as a paid subscriber. The system counts how often you park, ensures you’re within your subscription limits, and can be revoked if you stop paying. Anyone with your pass could use it, which is why you keep it in your car.

Code Example

// API Key in header (recommended)
fetch('https://api.weather.com/v1/forecast', {
  headers: {
    'X-API-Key': 'YOUR-API-KEY-xxxxxxxxxxxxx'
  }
});

// API Key in query (less secure, visible in logs)
fetch('https://api.weather.com/v1/forecast?api_key=YOUR-API-KEY');

Diagram

sequenceDiagram
    participant C as Client App
    participant S as API Server
    participant DB as Key Database

    Note over C: API Key can be sent in
different locations

    rect rgb(240, 248, 255)
        Note over C,S: Option 1: Header (Recommended)
        C->>S: GET /api/weather
X-API-Key: sk_live_abc123
    end

    rect rgb(255, 248, 240)
        Note over C,S: Option 2: Query Parameter (Less Secure)
        C->>S: GET /api/weather?api_key=sk_live_abc123
    end

    rect rgb(240, 255, 240)
        Note over C,S: Option 3: Request Body
        C->>S: POST /api/weather
{"api_key": "sk_live_abc123"}
    end

    S->>DB: Lookup API Key
    DB-->>S: Key Data: owner, permissions,
rate limits, status

    alt Key Valid & Active
        Note over S: Check rate limits
Log usage for billing
        S-->>C: 200 OK + Response Data
    else Key Invalid/Revoked
        S-->>C: 401 Unauthorized
    else Rate Limit Exceeded
        S-->>C: 429 Too Many Requests
    end

Security Notes

Standards & RFCs