Authentication — API Keys, JWT, OAuth2

API Keys: Simple Identification

API Keys serve as the most straightforward form of authentication, acting essentially as a long-lived password tied to a specific client or service. When a request is made, the client attaches this secret token to the header, allowing the server to verify the source without re-authenticating every single request. The fundamental logic here is identity binding: if the server sees the correct key, it assumes the request is coming from the known entity that owns that key. While remarkably simple to implement, API keys suffer from significant security drawbacks; they are static and often end up hardcoded in source files or intercepted during transmission. Because they are not easily rotated and lack granular permission scopes, they are best suited for public data access or internal server-to-server communication where the exposure risk is managed by strict network-level security controls.

# Example of API key verification in a request header
# Client sends: GET /data HTTP/1.1
# X-API-Key: secret_key_abc123

def verify_api_key(request):
    key = request.headers.get('X-API-Key')
    # Check if key exists in the database
    if key == "secret_key_abc123":
        return True
    return False

JSON Web Tokens: Stateless Identity

JSON Web Tokens, or JWTs, represent a paradigm shift towards stateless authentication by embedding identity and claims directly into a cryptographically signed token. Instead of querying a central database for every incoming request to check if a user is logged in, the server decodes the JWT and validates the signature using a known secret or public key. This approach is highly efficient for distributed systems because the server needs no internal state about the session; all necessary information is self-contained. The security of JWTs relies entirely on the integrity of the signature; if an attacker can forge the signature, they can spoof any identity. Therefore, you must always ensure tokens have an expiration timestamp to limit the window of opportunity for intercepted tokens, and avoid placing highly sensitive data like passwords directly inside the payload because tokens are easily decoded.

# Simplified JWT decoding and validation
import jwt # Assume standard library for token processing

def authorize_user(token):
    try:
        # Validate signature and expiration
        payload = jwt.decode(token, "my_secret_key", algorithms=["HS256"])
        return payload['user_id']
    except jwt.ExpiredSignatureError:
        return "Token has expired"

OAuth2: Delegated Authorization

OAuth2 is not strictly an authentication protocol but an authorization framework that allows a user to grant a third-party application limited access to their resources without exposing their credentials. It works through a dance of tokens: an authorization server issues an access token to the client after the user grants permission. The core strength of OAuth2 lies in the principle of least privilege, as these tokens are often scoped to specific actions—like reading profile data but not deleting it. By decoupling the resource server from the authorization server, you gain the ability to manage access across many different services centrally. This is crucial for modern ecosystems where users expect to interact with multiple platforms seamlessly while maintaining control over their private data, ensuring that your system never sees the actual user password.

# Simplified flow of using an OAuth2 access token
# Authorization header typically follows Bearer scheme

def access_protected_resource(auth_header):
    # Extract 'Bearer <token>'
    token = auth_header.split(" ")[1]
    # Resource server validates token with auth server
    if validate_token_with_provider(token):
        return "Resource data access granted"

Implementing Bearer Authentication

The Bearer token pattern is the standard way to transmit security tokens in HTTP headers, following the OAuth2 and JWT specifications. The name 'Bearer' implies that whoever holds the token is authorized to use it, which highlights why secure transport over HTTPS is non-negotiable. If a connection is not encrypted, any middleman can capture the raw token string and replay the request as if they were the legitimate user. By standardizing this behavior in the 'Authorization' header, you ensure interoperability between your APIs and any standard client libraries. Always validate the token format before processing, and treat the token as a temporary credential that should be rejected immediately if the server detects any anomalous behavior or if the token has been explicitly revoked through a back-end blacklist mechanism.

# Standard Bearer header usage implementation

headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "Content-Type": "application/json"
}
# The server parses the 'Bearer' prefix to find the token payload

Security Best Practices and Rotation

Regardless of the technology chosen, the security of your API depends on lifecycle management. Static credentials should be rotated regularly to minimize the impact of a potential breach, and tokens must always be short-lived to reduce the scope of valid theft. Implement logging and monitoring to detect unusual request patterns, such as a single API key being used from different geographical locations simultaneously. Furthermore, never transmit tokens in URL query parameters, as these are frequently logged in server logs and browser histories. Instead, keep them in headers or encrypted cookies. Security is a layered process; authenticate the request to establish identity, authorize the action to enforce permissions, and use transport layer security to protect the data in transit from eavesdroppers or malicious manipulators.

# Example of simple token expiry enforcement
import time

def check_expiry(token_payload):
    current_time = time.time()
    # Ensure the current time is before the exp claim
    if current_time < token_payload['exp']:
        return True
    return False # Force re-authentication

Interview questions

All REST API Design interview questions →

Check yourself

Take the full REST API Design quiz →