# RealWorld API User Authentication Endpoints: Complete REST Reference

> Explore the RealWorld API authentication endpoints for login, registration, and profile management. Get a complete REST reference secured with JWT tokens for seamless user operations.

- Repository: [Thinkster/realworld](https://github.com/gothinkster/realworld)
- Tags: api-reference
- Published: 2026-02-28

---

**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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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:

```http
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`:

```javascript
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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/apps/documentation/src/content/docs/specifications/backend/endpoints.md)** – Human-readable documentation listing all backend routes including authentication endpoints.

- **[`specs/e2e/helpers/api.ts`](https://github.com/gothinkster/realworld/blob/main/specs/e2e/helpers/api.ts)** – Test helper utilities that wrap authentication API calls for end-to-end testing suites.

- **[`specs/e2e/auth.spec.ts`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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`](https://github.com/gothinkster/realworld/blob/main/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).