API Authentication Methods¶

A guide to common API authentication methods and when to use each.

Overview¶

Method	Security	Complexity	Best For
API Keys	Basic	Low	Simple integrations, server-to-server
Bearer Tokens	Good	Medium	User sessions, short-lived access
OAuth 2.0	High	High	Third-party access, user authorisation
Basic Auth	Low	Low	Internal APIs, legacy systems
JWT	Good	Medium	Stateless authentication

API Keys¶

A simple string that identifies and authenticates the caller.

How It Works¶

You generate an API key from the service
Include the key in every request
The server validates the key and grants access

Implementation¶

In header (recommended):

GET /api/data HTTP/1.1
Host: api.example.com
X-API-Key: your_api_key_here

In query parameter:

GET /api/data?api_key=your_api_key_here

In header (Authorization):

GET /api/data HTTP/1.1
Authorization: ApiKey your_api_key_here

Pros and Cons¶

Pros:

Simple to implement
Easy to revoke and rotate
Good for server-to-server communication

Cons:

No built-in expiration
If leaked, full access until revoked
Doesn't identify individual users

Best Practices¶

Store keys in environment variables, never in code
Use different keys for development and production
Rotate keys periodically
Monitor key usage for anomalies

Bearer Tokens¶

A token passed in the Authorization header, typically short-lived.

How It Works¶

Client authenticates (login) to get a token
Token is included in subsequent requests
Server validates the token
Token expires after a set time

Implementation¶

GET /api/data HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pros and Cons¶

Pros:

Can be short-lived (limits damage if leaked)
Can carry user information (if JWT)
Standard format widely supported

Cons:

Requires token refresh logic
More complex than API keys
Must be stored securely on client

OAuth 2.0¶

An authorisation framework for granting limited access to third parties.

How It Works¶

User is redirected to the authorisation server
User logs in and grants permission
App receives an authorisation code
App exchanges code for access token
App uses token to access resources

Common Flows¶

Authorization Code (web apps):

1. Redirect to: https://auth.example.com/authorize?
     client_id=YOUR_CLIENT_ID&
     redirect_uri=YOUR_CALLBACK&
     response_type=code&
     scope=read

2. User logs in and approves

3. Callback receives: https://yourapp.com/callback?code=AUTH_CODE

4. Exchange code for token:
   POST /oauth/token
   grant_type=authorization_code&
   code=AUTH_CODE&
   client_id=YOUR_CLIENT_ID&
   client_secret=YOUR_SECRET

Client Credentials (server-to-server):

POST /oauth/token
grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_SECRET

Pros and Cons¶

Pros:

Users don't share passwords with third parties
Granular permissions (scopes)
Tokens can be revoked
Industry standard

Cons:

Complex to implement
Requires understanding of flows
Multiple round trips for setup

Basic Authentication¶

Username and password encoded in the header.

How It Works¶

Combine username and password: username:password
Base64 encode: dXNlcm5hbWU6cGFzc3dvcmQ=
Include in Authorization header

Implementation¶

GET /api/data HTTP/1.1
Host: api.example.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Pros and Cons¶

Pros:

Simple to implement
Built into HTTP standard
Supported everywhere

Cons:

Credentials sent with every request
Only secure over HTTPS
No built-in session management

Best Practices¶

Always use HTTPS - Basic auth is plain text (base64 is not encryption)
Use for internal/trusted systems only
Consider for initial authentication to get a token

JWT (JSON Web Tokens)¶

Self-contained tokens that carry claims about the user.

Structure¶

header.payload.signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4ifQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622
}

Common Claims¶

Claim	Meaning
`sub`	Subject (user ID)
`iat`	Issued at (timestamp)
`exp`	Expiration (timestamp)
`iss`	Issuer
`aud`	Audience

Pros and Cons¶

Pros:

Stateless (no server-side session needed)
Can carry user data in payload
Can be verified without database lookup

Cons:

Cannot be invalidated before expiry (unless using a blocklist)
Payload is readable (not encrypted, just signed)
Token size grows with claims

Best Practices¶

Keep tokens short-lived
Don't store sensitive data in payload
Use refresh tokens for long sessions
Verify signature on every request

Choosing the Right Method¶

Use API Keys when:¶

Building server-to-server integrations
You need simple, long-lived credentials
The API doesn't need user-level access control

Use Bearer Tokens / JWT when:¶

You need short-lived access
You want stateless authentication
Building mobile or SPA applications

Use OAuth 2.0 when:¶

Third parties need access to user data
You need granular permissions (scopes)
Building a platform with external integrations

Use Basic Auth when:¶

Integrating with legacy systems
Internal tools with trusted clients
As a step to exchange for tokens

Security Checklist¶

Always use HTTPS
Store credentials in environment variables
Never log tokens or keys
Implement token expiration
Rate limit authentication attempts
Monitor for unusual access patterns
Have a process for rotating credentials