RealWorld API User Authentication Endpoints: Complete REST Reference

The RealWorld API provides four RESTful authentication endpoints—POST /users/login for user authentication, POST /users for account registration, GET /user for retrieving the current user profile, and PUT /user for updating user details—all secured via JWT tokens defined in the OpenAPI specification.

The RealWorld demo application serves as the "mother of all demo apps," providing a standardized specification for full-stack implementations. Understanding the RealWorld API user authentication endpoints is critical for developers building compatible backends or frontend clients, as these routes handle identity management through a stateless, token-based security model.

Authentication Endpoints Overview

RealWorld’s backend defines a concise set of RESTful routes grouped under the "User and Authentication" tag in the OpenAPI specification:

Operation	HTTP Method	Path	Purpose
Login	POST	/users/login	Authenticates an existing user and returns a JWT token
Register	POST	/users	Creates a new user account and returns a JWT token
Get Current User	GET	/user	Retrieves the profile of the authenticated user
Update Current User	PUT	/user	Updates fields of the authenticated user

Detailed Endpoint Specifications

Login – POST /users/login

The login endpoint authenticates existing users and issues a JWT token. According to the source code analysis, this operation is defined at lines 22‑38 in specs/api/openapi.yml.

The endpoint accepts a JSON payload containing email and password within a user object, returning a user object that includes the token field for subsequent authenticated requests.

Register – POST /users

New account creation is handled by the registration endpoint, specified at lines 39‑55 in specs/api/openapi.yml. This route accepts username, email, and password within the request body and returns the newly created user object along with a valid JWT token for immediate authentication.

Get Current User – GET /user

To retrieve the currently authenticated user's profile, clients send a GET request to /user. This endpoint is defined at lines 55‑63 in specs/api/openapi.yml and requires a valid JWT token in the Authorization header using the format Token <jwt>.

Update Current User – PUT /user

Profile updates are handled via the PUT /user endpoint defined at lines 71‑88 in specs/api/openapi.yml. This route accepts optional fields including email, username, bio, image, and password, allowing partial updates to the user's profile information.

JWT Security Implementation

All protected authentication routes utilize the Token security scheme defined near lines 908‑919 in specs/api/openapi.yml. Clients must include the JWT in the Authorization header using the prefix Token followed by a space and the token string:

Authorization: Token eyJhbGciOiJIUzI1NiIs...

JavaScript Implementation Examples

Below are practical implementations using the Node.js fetch API against the official RealWorld API base URL https://api.realworld.show/api:

const API_BASE = 'https://api.realworld.show/api';

// Authenticate existing user
async function login(email, password) {
  const resp = await fetch(`${API_BASE}/users/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ user: { email, password } })
  });
  const { user } = await resp.json();
  return user.token; // JWT for subsequent calls
}

// Create new account
async function register(username, email, password) {
  const resp = await fetch(`${API_BASE}/users`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ user: { username, email, password } })
  });
  const { user } = await resp.json();
  return user.token;
}

// Retrieve current user profile
async function getCurrentUser(token) {
  const resp = await fetch(`${API_BASE}/user`, {
    method: 'GET',
    headers: { Authorization: `Token ${token}` }
  });
  const { user } = await resp.json();
  return user;
}

// Update user profile (partial updates supported)
async function updateCurrentUser(token, updates) {
  const resp = await fetch(`${API_BASE}/user`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Token ${token}`
    },
    body: JSON.stringify({ user: updates })
  });
  const { user } = await resp.json();
  return user;
}

Key Source Files

The authentication system is implemented across the following files in the gothinkster/realworld repository:

• specs/api/openapi.yml – OpenAPI 3.1 definition containing all endpoint specifications, request/response schemas, and security definitions (see lines 22‑38 for login, 39‑55 for registration, 55‑63 for get user, and 71‑88 for updates).

• apps/documentation/src/content/docs/specifications/backend/endpoints.md – Human-readable documentation listing all backend routes including authentication endpoints.

• specs/e2e/helpers/api.ts – Test helper utilities that wrap authentication API calls for end-to-end testing suites.

• specs/e2e/auth.spec.ts – Cypress/Playwright test specifications exercising the login, registration, and current user flows.

Summary

• RealWorld provides exactly four authentication endpoints: POST /users/login, POST /users, GET /user, and PUT /user.
• All endpoints are strictly defined in specs/api/openapi.yml with specific line references for each operation.
• Authentication relies on JWT tokens passed via the Authorization: Token <jwt> header scheme.
• The API supports partial updates for user profiles through the PUT /user endpoint.
• Official test suites in specs/e2e/ demonstrate practical implementation patterns for these endpoints.

Frequently Asked Questions

What authentication method does the RealWorld API use?

The RealWorld API uses JWT (JSON Web Token) authentication. According to the OpenAPI specification in specs/api/openapi.yml, protected endpoints require the Token security scheme, where clients must provide the header Authorization: Token <jwt>.

How do I obtain a JWT token from the RealWorld API?

You obtain a JWT token by calling either POST /users/login with existing credentials or POST /users to register a new account. Both endpoints return a user object containing the token field, as implemented in specs/api/openapi.yml lines 22‑55.

What fields can be updated via the RealWorld user update endpoint?

The PUT /user endpoint supports updating email, username, bio, image, and password. The endpoint accepts partial payloads, allowing clients to update only specific fields without resubmitting the entire user object, as defined in lines 71‑88 of the OpenAPI specification.

Where is the RealWorld API authentication specification documented?

The authoritative source is specs/api/openapi.yml in the gothinkster/realworld repository, which contains the complete OpenAPI 3.1 definition including all four authentication endpoints, request schemas, and the Token security definition (lines 908‑919).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}