Authentication

Overview

Authentication answers the question "who are you?" for each API request. Because HTTP is stateless, clients must prove their identity on every call, usually by sending a credential in a header. Common schemes include API keys, bearer tokens, and JSON Web Tokens (JWTs). Sending credentials only over HTTPS is essential so they can't be intercepted.

Syntax / Usage

Credentials are passed in the Authorization header. Bearer tokens are the most common pattern for user-facing APIs.

# Bearer token (e.g. OAuth access token or JWT)
GET /me HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.abc123

# API key in a custom header
GET /reports HTTP/1.1
X-API-Key: sk_live_9f8a7b6c5d

Examples

A valid token returns the protected resource:

GET /me HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

HTTP/1.1 200 OK
{ "id": 42, "name": "Ada Lovelace" }

A missing or invalid token returns 401, prompting the client to authenticate:

GET /me HTTP/1.1

HTTP/1.1 401 Unauthorized
{ "error": { "code": "unauthorized", "message": "Missing token" } }

Common Mistakes

• Sending credentials over plain HTTP instead of HTTPS
• Putting API keys or tokens in the URL, where they get logged
• Confusing authentication (who you are) with authorization (what you can do)
• Using 403 Forbidden when the credential is missing — that's 401
• Never expiring or rotating tokens, so a leaked one works forever

See Also

api-design-status-codes api-design-error-handling api-design-rest-basics