API Key Security Basics

Welcome to the first lesson of our course on API Key Authentication & Security. In this lesson, you will learn the basics of generating and securely storing API keys — a fundamental part of building secure web applications and APIs. API keys are unique codes that allow applications or users to access certain features or data. They are widely used to control and monitor access to APIs, and they help keep your services safe from unauthorized use.

By the end of this lesson, you will understand how to generate strong, random API keys, how to store them securely in your database, and how to set up an endpoint for users to create their own API keys. You will also learn about best practices for managing API keys throughout their lifecycle. This knowledge will prepare you for the hands-on exercises that follow, where you will practice these skills in a real coding environment.

Let's start by looking at the data model for API keys. In our example, we use SQLAlchemy, a popular ORM for Python, to define the ApiKey model. This model represents how API keys are stored in the database. Here is the code for the model:

from sqlalchemy import Column, Integer, String, Boolean, DateTime, ForeignKey
from datetime import datetime
from ..database import Base

class ApiKey(Base):
    __tablename__ = 'api_keys'
    
    id = Column(Integer, primary_key=True, autoincrement=True)
    userId = Column(Integer, ForeignKey('users.id'), nullable=False)
    name = Column(String, nullable=False)
    keyHash = Column(String, nullable=False, unique=True)
    isActive = Column(Boolean, default=True)
    expiresAt = Column(DateTime, nullable=False)
    createdAt = Column(DateTime, default=datetime.utcnow)

Each API key has several important properties. The id is a unique identifier for each key. The userId links the key to a specific user in your system using a foreign key relationship. The name allows users to label their keys for easy identification. The keyHash stores a hashed version of the API key, which is important for security (we will discuss this sooner). The isActive field lets you enable or disable keys without deleting them, and expiresAt sets an expiration date for each key. This structure helps you manage API keys safely and efficiently.

When creating an API key, it is important to make sure it is random and hard to guess. In our example, we use Python's built-in secrets module to generate a secure key. Here is the relevant code:

import secrets
import bcrypt

async def generate_api_key():
    # Generate 32 random bytes = 256 bits of security
    random_bytes = secrets.token_bytes(32)
    key = random_bytes.hex()
    
    # Hash the key for secure storage
    key_hash = bcrypt.hashpw(key.encode(), bcrypt.gensalt(12)).decode('utf-8')
    
    # Return formatted key with pastebin prefix
    formatted_key = f'pb_{key}'
    
    return {'key': formatted_key, 'keyHash': key_hash}

The function secrets.token_bytes(32) generates 32 random bytes, which gives us 256 bits of entropy. This makes the key very difficult to guess or brute-force. We then convert these bytes to a hexadecimal string using the .hex() method, which is easy to store and use. Adding a prefix like pb_ helps identify the key as belonging to your application, which can be useful for debugging or logging.

Storing raw API keys in your database is risky. If your database is ever compromised, attackers could use those keys to access your services. To prevent this, we hash the API key before saving it. In our code, we use the bcrypt library for hashing:

key_hash = bcrypt.hashpw(key.encode(), bcrypt.gensalt(12)).decode('utf-8')

Hashing transforms the original key into a fixed-length string that cannot be reversed. Even if someone gains access to your database, they cannot recover the original API key from the hash. When a user presents an API key, you can hash the provided key and compare it to the stored hash to verify its validity. This is the same approach used for storing passwords securely.

Now let's look at how we allow users to create new API keys. We use a FastAPI route that handles POST requests to /create. This route is protected by a JWT authentication function, which checks that the user is logged in and authorized. Here is the main part of the route:

from fastapi import APIRouter, Depends, HTTPException, Request
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select, func
from datetime import datetime, timedelta
from ..database import get_db
from ..models.user import User
from ..models.api_key import ApiKey
from ..config import JWT_SECRET_KEY
from jose import jwt

router = APIRouter()

# JWT authentication middleware
async def verify_token(authorization: str, db: AsyncSession):
    if not authorization or not authorization.startswith('Bearer '):
        raise HTTPException(status_code=401, detail="Missing authorization header")
    
    token = authorization.split(' ')[1]
    
    try:
        decoded = jwt.decode(token, JWT_SECRET_KEY, algorithms=['HS256'])
        user_id = decoded['userId']
        
        result = await db.execute(select(User).where(User.id == user_id))
        user = result.scalar_one_or_none()
        
        if not user:
            raise HTTPException(status_code=404, detail="User not found")
        
        return user
    except jwt.JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

# Create new API key
@router.post("/create")
async def create_api_key(request: Request, db: AsyncSession = Depends(get_db)):
    authorization = request.headers.get('authorization')
    user = await verify_token(authorization, db)
    
    data = await request.json()
    name = data.get('name')
    
    # Basic validation
    if not name or len(name) < 3:
        raise HTTPException(status_code=400, detail="API key name must be at least 3 characters")
    
    # Limit to 3 API keys per user
    result = await db.execute(
        select(func.count(ApiKey.id)).where(ApiKey.userId == user.id, ApiKey.isActive == True)
    )
    existing_keys = result.scalar()
    
    if existing_keys >= 3:
        raise HTTPException(status_code=400, detail="Maximum 3 API keys allowed per user")
    
    # Generate secure API key
    key_data = await generate_api_key()
    
    # Set expiration to 1 year from now
    expires_at = datetime.utcnow() + timedelta(days=365)
    
    # Save to database
    api_key = ApiKey(
        userId=user.id,
        name=name,
        keyHash=key_data["keyHash"],
        expiresAt=expires_at
    )
    
    db.add(api_key)
    await db.commit()
    await db.refresh(api_key)
    
    return {
        "message": "API key created successfully",
        "apiKey": {
            "id": api_key.id,
            "name": name,
            "key": key_data["key"],  # Only shown once during creation
            "expiresAt": expires_at.isoformat()
        },
        "warning": "Store this key securely. It will not be shown again."
    }

When a user requests a new API key, the server first checks that the request is valid and that the user does not already have too many active keys. It then generates a secure key, hashes it, and saves the hash in the database. The raw key is returned to the user only once, with a warning to store it securely. If the user loses the key, they will need to generate a new one.

A typical response from this endpoint might look like:

{
  "message": "API key created successfully",
  "apiKey": {
    "id": 7,
    "name": "My App Key",
    "key": "pb_4f3c2e1a...",
    "expiresAt": "2025-06-10T12:34:56.789Z"
  },
  "warning": "Store this key securely. It will not be shown again."
}

Managing API keys is not just about generating and storing them. You should also think about their lifecycle. Each key in our model has an expiresAt field, which means keys will automatically become invalid after a certain date. The isActive field allows you to deactivate keys without deleting them, which is useful if a key is compromised or is no longer needed.

Here are some tips for managing API keys safely:

• Always hash API keys before storing them.
• Limit the number of active keys per user to reduce risk.
• Set expiration dates for keys and encourage users to rotate them regularly.
• Never log or display the raw API key after creation.
• Encourage users to store their keys securely, such as in environment variables or secret managers.

Following these practices will help keep your application and your users safe.

In this lesson, you learned how to design a secure API key model, generate strong random keys, hash them for safe storage, and create an endpoint for users to generate their own API keys. You also learned about best practices for managing API keys throughout their lifecycle.

You are now ready to move on to the hands-on practice exercises, where you will apply what you have learned in a real coding environment. Remember, on CodeSignal, all the necessary libraries are pre-installed, so you can focus on writing and testing your code. Great job reaching the end of this lesson! Keep up the good work, and let's continue building your skills in API key authentication and security.