Authentication & Authorization

Relevant source files

• .gitignore
• CONTRIBUTING.md
• README.md
• api/Conduit.postman_collection.json
• api/README.md
• api/openapi.yml
• apps/api/server/routes/api/articles/index.get.ts
• apps/documentation/src/assets/swagger.json
• apps/documentation/src/content/docs/specifications/frontend/api.md

This document explains the JWT-based authentication system used throughout the RealWorld API specification and how endpoints enforce authorization. It covers token generation, the authorization header format, authentication flows, and which endpoints require authentication versus those that accept optional authentication.

For information about the data models returned during authentication (User and Profile schemas), see Data Models & Schemas. For details on implementing authentication in the reference backend, see Authentication Implementation.

---

Overview

The RealWorld API uses a token-based authentication system built on JSON Web Tokens (JWT). The security scheme is defined as an API key that must be passed in the Authorization header for protected endpoints.

Sources: api/openapi.yml908-918

---

Security Scheme Definition

The API specification defines a security scheme named Token that uses the API key authentication type:

Property	Value
Type	apiKey
Header Name	Authorization
Location	header
Token Format	Token xxxxxx.yyyyyyy.zzzzzz

The JWT token must be prefixed with the literal string "Token " (with a space) when included in the Authorization header.

Sources: api/openapi.yml908-918

---

Authentication Flow

Registration Process:

1. Client sends POST request to /users with credentials
2. API hashes the password and creates user record
3. API generates JWT token containing user identifier
4. API returns User object with token included

Login Process:

1. Client sends POST request to /users/login with credentials
2. API verifies email and password against stored hash
3. API generates new JWT token
4. API returns User object with fresh token

Sources: api/openapi.yml22-54 api/Conduit.postman_collection.json10-177

---

Token Generation & Validation

Token Generation

JWT tokens are generated by the API in two scenarios:

• During user registration (POST /users)
• During user login (POST /users/login)

The token is returned as part of the User schema in the response body under the token property.

Token Structure

The JWT follows the standard three-part structure:

Token HEADER.PAYLOAD.SIGNATURE

The prefix "Token " is required and must precede the actual JWT string.

Token Validation

For protected endpoints, the API must:

1. Extract the Authorization header value
2. Verify the "Token " prefix exists
3. Extract and validate the JWT signature
4. Decode the payload to retrieve the user identifier
5. Verify the user exists and is valid

Sources: api/openapi.yml908-918 api/Conduit.postman_collection.json120-177

---

Authorization Header Format

All authenticated requests must include the Authorization header in the following format:

Authorization: Token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaWF0IjoxNjg5...

Example from Postman Tests:

The test collection demonstrates proper header usage:

After successful login, the token is stored and reused across subsequent requests.

Sources: api/Conduit.postman_collection.json214-217 api/Conduit.postman_collection.json269-272

---

Endpoint Authorization Matrix

Endpoints Requiring Authentication

The following endpoints require the Token security scheme:

Endpoint	Method	Purpose
/user	GET	Get current user
/user	PUT	Update current user
/profiles/{username}/follow	POST	Follow a user
/profiles/{username}/follow	DELETE	Unfollow a user
/articles/feed	GET	Get personalized article feed
/articles	POST	Create an article
/articles/{slug}	PUT	Update an article
/articles/{slug}	DELETE	Delete an article
/articles/{slug}/comments	POST	Create a comment
/articles/{slug}/comments/{id}	DELETE	Delete a comment
/articles/{slug}/favorite	POST	Favorite an article
/articles/{slug}/favorite	DELETE	Unfavorite an article

Sources: api/openapi.yml69-70 api/openapi.yml86-87 api/openapi.yml135-136 api/openapi.yml159-160 api/openapi.yml179-180 api/openapi.yml231-232 api/openapi.yml281-282 api/openapi.yml308-309 api/openapi.yml357-358 api/openapi.yml391-392 api/openapi.yml416-417 api/openapi.yml440-441

Endpoints NOT Requiring Authentication

The following endpoints are publicly accessible:

Endpoint	Method	Purpose
/users	POST	Register new user
/users/login	POST	Login existing user
/profiles/{username}	GET	Get user profile
/articles	GET	List articles globally
/articles/{slug}	GET	Get single article
/articles/{slug}/comments	GET	Get article comments
/tags	GET	Get all tags

Sources: api/openapi.yml39-54 api/openapi.yml22-38 api/openapi.yml89-111 api/openapi.yml182-213 api/openapi.yml234-254 api/openapi.yml310-332 api/openapi.yml442-453

---

Optional Authentication

Some endpoints support optional authentication, where behavior differs based on whether a valid token is provided:

GET /articles

• Unauthenticated: Returns all articles (subject to demo account restrictions)
• Authenticated: Returns articles with personalized favorited and following flags

GET /articles/{slug}

• Unauthenticated: Returns article without user-specific data
• Authenticated: Returns article with user's favorite/follow status

GET /profiles/{username}

• Unauthenticated: Returns profile with following: false
• Authenticated: Returns profile with accurate following status

Sources: api/openapi.yml182-213 api/openapi.yml234-254 api/openapi.yml89-111

---

Reference Implementation Pattern

The reference implementation uses a custom event handler pattern to enforce authentication:

Code Example

The GET /articles endpoint demonstrates optional authentication:

The auth parameter is either:

• undefined (no token provided)
• {id: number} (valid token with user ID)

The handler checks for authentication to apply personalized filtering:

Sources: apps/api/server/routes/api/articles/index.get.ts1-114

---

Error Responses

401 Unauthorized

Returned when authentication is required but the token is missing or invalid:

403 Forbidden

Returned when the user is authenticated but not authorized to perform the action (e.g., trying to delete another user's article):

Sources: api/openapi.yml767-796

---

Test Collection Authentication Flow

The test collection demonstrates stateful authentication:

1. Register Test - Creates user, receives token
2. Login Test - Authenticates existing user, receives token
3. Login and Remember Token Test - Stores token in global variables for reuse
4. Subsequent Tests - Use stored token via {{token}} variable

Sources: api/Conduit.postman_collection.json10-342

---

Security Considerations

Token Expiration

The OpenAPI specification does not mandate token expiration, but implementations should include:

• Expiration timestamps in JWT payload (exp claim)
• Reasonable expiration windows (e.g., 7-30 days)
• Token refresh mechanisms for long-lived sessions

Password Security

• Passwords must be hashed before storage (never stored in plaintext)
• Use strong hashing algorithms (bcrypt, Argon2)
• Include salt to prevent rainbow table attacks

Token Transmission

• Tokens should only be transmitted over HTTPS in production
• Tokens should not be logged or exposed in error messages
• Tokens should be stored securely by clients (HTTP-only cookies or secure storage)

Sources: api/openapi.yml908-918

---

Implementation Checklist

When implementing authentication for a RealWorld backend:

• Generate JWT tokens on registration and login
• Include token in User response object
• Accept Authorization: Token <jwt> header format
• Validate token signature and expiration
• Extract user ID from valid tokens
• Return 401 for invalid/missing tokens on protected endpoints
• Support optional authentication for appropriate endpoints
• Hash passwords with strong algorithm
• Implement token-based ownership checks (403 errors)
• Test authentication flow with provided Postman collection

Sources: api/openapi.yml908-918 api/Conduit.postman_collection.json1-342