Auth Architecture: Actions vs. Resources

When designing authentication APIs, you hit a fork in the road early on:

Should auth be modeled as actions (e.g., /auth/login) or as resources (e.g., /sessions)?

While both get the job done, they communicate fundamentally different mental models. One describes a task; the other describes a state. Let’s break down why that distinction matters.

The Action-Based Approach (RPC Style)

This is the industry "default." It’s what most of us learn first:

POST /auth/login
POST /auth/register
POST /auth/refresh
POST /auth/logout

It’s intuitive because it mirrors the UI. Your frontend has a /login page, so your backend has a /login endpoint. It reads like a checklist of user intentions.

However, technically speaking, this is RPC (Remote Procedure Call) design. You are exposing verbs rather than entities. You’re telling the server to "run the login function," treating authentication as a series of commands rather than a system of persistent data.

This works perfectly for MVPs or simple monoliths, but it tends to obscure architectural boundaries as the system grows.

The Resource-Oriented Approach (REST Style)

Now, consider the alternative:

POST   /users
POST   /sessions
GET    /sessions
DELETE /sessions/{id}
POST   /sessions/refresh

In this model, you aren't "logging in." You are creating a session resource.

This is a subtle but profound shift. Instead of focusing on the act of authenticating, you focus on the resulting entity and its lifecycle. This alignment with REST principles offers much more flexibility.

Why a "Session" is a True Resource

In REST, a resource is defined by three things: State, Identity, and Lifecycle. A session checks all three boxes.

1. State

A session isn't just a moment in time; it’s a data object. It holds:

• user_id and issued_at
• expires_at
• Device metadata (IP, User-Agent)
• Token status (Active, Revoked, Expired)

If it holds state, it’s a resource.

2. Identity

If a user logs in from their iPhone, Laptop, and Tablet simultaneously, they have three distinct sessions.

• Session A: iPhone
• Session B: Laptop
• Session C: Tablet

Modeling these as resources allows you to treat them individually. You can list them (GET /sessions) or revoke one specifically (DELETE /sessions/{id}) without affecting the others.

3. Lifecycle

Anything that can be created, retrieved, updated, and destroyed has a lifecycle.

• Auth is the logic that validates the credentials.
• The Session is the artifact that persists.

UI Language vs. Domain Modeling

The reason /auth/login feels "right" to many is that it mimics frontend routing. It’s built around the user's journey.

But a robust backend shouldn't necessarily speak the language of the UI; it should speak the language of the domain. By using POST /sessions, you decouple your API from the specific workflow of your website and move toward a more universal data model.

Which One Should You Choose?

Stick with Action-Based if:

• You’re building a small project or a prototype.
• You’re working on a simple internal tool.
• Developer speed and "at-a-glance" simplicity are the top priorities.

Move to Resource-Based if:

• You need multi-device management (e.g., "Log out of all other devices").
• You’re building an enterprise-grade system or a microservices mesh.
• You need a clear audit trail of session lifecycles.
• You want a clean, maintainable API that won't require a rewrite in two years.

The Clean Mental Model

To build better systems, stop grouping everything under "Auth." Start separating them:

• User: Who they are.
• Account/Credentials: How they prove who they are.
• Authentication: The process of verification.
• Session: The resource representing their authenticated state.

The Bottom Line: You aren't just designing "login endpoints"; you are designing identity and state management. If it has a state and a lifecycle, treat it like a resource.

Auth is a process. A session is a resource. Design accordingly.

Album of the blog: