API Authentication

Every API request arrives with an implicit question: should I trust you?

Without authentication, the answer is always yes—to everyone. Anyone can read your data, modify your resources, impersonate your users. Your API becomes a door without a lock in a neighborhood where everyone has learned there's no lock.

Authentication is how APIs verify identity. It answers "who are you?" so the API can decide whether to let you in and what you're allowed to touch once inside.

Authentication vs. Authorization

These two concepts work together but solve different problems.

Authentication verifies identity. It answers "who are you?" A valid API key or access token proves you are who you claim to be.

Authorization determines permissions. It answers "what can you do?" Being authenticated doesn't mean you can delete all users or access someone else's private data.

Every API request needs both: first confirm identity, then check permissions.

API Keys

API keys are the simplest authentication mechanism—unique strings issued to each application.

You register with an API provider and receive a key (a long random string). Include it with every request:

GET /users
Authorization: ApiKey sk_live_abc123def456

API keys work well for server-to-server communication. They're simple to implement, easy for developers to use, and enable tracking usage per application.

The critical limitation: API keys identify applications, not users. They have no built-in expiration, no granular permissions, and become dangerous if exposed. Never embed API keys in client-side code—mobile apps and JavaScript can be decompiled or inspected, exposing your key to anyone who looks.

Best practices: Rotate keys periodically. Use different keys for development and production. Transmit only over HTTPS.

Bearer Tokens

A bearer token is exactly what it sounds like: whoever bears it gets in. Like a movie ticket—the theater doesn't care who bought it, only who's holding it.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The flow: authenticate once with credentials, receive a token, include that token with subsequent requests. The server validates the token and processes the request.

This is better than sending credentials repeatedly. Tokens can expire, carry permissions, and be revoked without changing passwords. If someone steals your token, you revoke it. If someone steals your password, you have a bigger problem.

OAuth 2.0

OAuth solves an elegant problem: how do you let a third-party app access your data without giving them your password?

The answer is delegation. You're giving a stranger permission to pretend to be you—but only for specific things, and only until you change your mind.

The flow: You want a third-party app to post to your Twitter. The app redirects you to Twitter. You log into Twitter directly (the app never sees your password). You approve specific permissions ("can post tweets" but not "can delete your account"). Twitter gives the app a token. The app uses that token to act on your behalf.

The components:

• Access tokens grant API access, typically short-lived (hours or days)
• Refresh tokens obtain new access tokens without bothering the user again
• Scopes define what the app can do—"read:posts" vs. "write:posts" vs. "delete:account"

OAuth is significantly more complex than API keys. Implementing it requires authorization servers, token management, scope validation, and refresh token handling. Most APIs use OAuth providers (Auth0, Okta, Firebase) rather than building their own.

JWT (JSON Web Tokens)

JWTs are self-contained tokens. Unlike opaque tokens that require the server to look up who they belong to, JWTs carry their own information.

A JWT has three parts separated by dots: header, payload, signature.

header.payload.signature

The payload contains claims—user ID, permissions, expiration time:

{
  "sub": "user123",
  "name": "John Doe",
  "role": "admin",
  "exp": 1735689600
}

The signature ensures the token hasn't been tampered with. If anyone modifies the payload, the signature won't match.

The advantage: No server-side session storage. Any service can validate a JWT independently—perfect for microservices.

The catch: JWTs can't be revoked before expiration without additional infrastructure. The payload is only base64-encoded, not encrypted—anyone can read it. And they're larger than simple tokens because they carry all that data.

Best practices: Short expiration times (15-60 minutes). Never store sensitive data in the payload. Validate signatures on every request.

HTTP Basic Authentication

Basic authentication sends username and password with each request, encoded in Base64:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Base64 is encoding, not encryption. Anyone intercepting the request can decode credentials instantly. Use basic authentication sparingly, only over HTTPS, and prefer token-based approaches for modern APIs.

Session-Based Authentication

Traditional web applications create sessions after login—the server stores session data and sends a session ID via cookie. Subsequent requests include the cookie.

For APIs, sessions are less common. They require stateful servers, don't work well across domains, and cookies can be problematic for non-browser clients. But they work well for APIs consumed by the same-origin web frontend.

Machine-to-Machine Authentication

When APIs talk to other APIs with no user involved, different patterns apply:

• Service accounts are dedicated accounts for applications
• Client credentials OAuth grants let services authenticate to each other
• Mutual TLS uses certificates for both client and server verification
• API keys work well for simple service-to-service authentication

Best Practices

Always use HTTPS. Credentials and tokens must be encrypted in transit. Never send authentication over plain HTTP.

Implement rate limiting per API key or user. This prevents brute force attacks and abuse.

Tokens should expire. Short-lived access tokens with refresh token rotation balance security and convenience.

Validate on every request. Never assume a token is still valid—check signatures, expiration, and permissions.

Never log credentials or tokens. Logging API keys or tokens creates vulnerabilities. Redact them.

Rotate API keys periodically. Provide mechanisms for developers to rotate keys without downtime.

Use separate credentials per environment. Development, staging, and production should have different keys.

Handling Authentication Failures

Return appropriate status codes:

• 401 Unauthorized for missing or invalid credentials
• 403 Forbidden for valid authentication but insufficient permissions

Provide clear error messages:

{
  "error": "authentication_required",
  "message": "No authentication credentials provided"
}

Don't reveal security details. Never say "password incorrect" vs. "username not found"—just "invalid credentials." This prevents attackers from confirming which usernames exist.

Implement lockouts after repeated failures. Log authentication failures for security monitoring.