# Use JWT for API authentication

* Status: accepted
* Date: 2026-04-26

## Context and Problem Statement

The API must authenticate requests from the Angular frontend. How should user identity be verified on each request?

## Decision Drivers

* Application is currently single-instance with no horizontal scaling requirement.
* Frontend already uses token-based auth (stores JWT in `localStorage` — see frontend ADR 0005).
* Simplicity of operation is preferred over session infrastructure.

## Considered Options

* JWT (JSON Web Tokens) with `express-jwt`
* Session-based authentication

## Decision Outcome

Chosen option: "JWT", because it is stateless (no session store needed), aligns with the frontend's existing token-based auth flow, and is simpler to operate for a single-instance deployment.

Tokens are issued on successful login (`jsonwebtoken` library, `bcrypt` for password hashing). Incoming requests are validated by `express-jwt`, which populates `req.auth` with the decoded payload. The `src/middlewares/auth.js` middleware wraps `express-jwt` and handles role-based access control (`Admin` role required for protected admin routes). The frontend sends tokens as `Authorization: Token <jwt>`.

### Positive Consequences

* Stateless — no session store needed. Horizontally scalable without sticky sessions.
* Single middleware handles auth for all routes.

### Negative Consequences

* Tokens cannot be invalidated server-side before expiry. Acceptable for this use case (internal application, low revocation risk).

## Pros and Cons of the Options

### JWT

* Good, because stateless — no session store infrastructure.
* Good, because works seamlessly with the frontend's `localStorage`-based token flow.
* Bad, because revocation requires token blacklisting, which adds state.

### Session-based authentication

* Good, because sessions can be invalidated immediately server-side.
* Bad, because requires a session store (Redis or database-backed) — adds infrastructure complexity.
* Bad, because sticky sessions or a shared store are needed in multi-instance deployments.

## Links

* Related to frontend [ADR 0005](../../adastra_app/docs/decisions/0005-jwt-authentication-localstorage.md)
* Security note: passwords are hashed with `bcrypt`. The JWT secret must be kept in environment configuration, never committed.