> For the complete documentation index, see [llms.txt](https://noora.gitbook.io/noora-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://noora.gitbook.io/noora-docs/api-reference/authentication-api.md).

# Authentication API

Authenticate users and fetch their profile information. For field-level schemas and status codes, see the Auth tag inside swagger.yaml or import the spec into Swagger UI/Editor.

> **Base path:** `/auth`  |  **Auth scheme:** JWT bearer token returned from the login or signup endpoints.

### POST `/auth/signup`

Create a new Outloud account and immediately issue a session token.

#### Request Body

| Field      | Type   | Notes                                                |
| ---------- | ------ | ---------------------------------------------------- |
| `username` | string | Required, unique per user.                           |
| `password` | string | Required, 8+ chars recommended.                      |
| `email`    | string | Optional, used for account recovery + notifications. |

#### Response

* `201 Created` – JSON payload shaped like `AuthResponse` (`token`, `user` object with `id`, `username`, `email`, timestamps).
* `400 Bad Request` – Input validation failed (duplicate username, weak password, etc.).

#### Sample

```bash
curl -X POST "$API_BASE_URL/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"username":"learner42","password":"super-secure","email":"me@example.com"}'
```

### POST `/auth/login`

Exchange user credentials for a short-lived JWT.

#### Request Body

| Field             | Type   | Notes                                                |
| ----------------- | ------ | ---------------------------------------------------- |
| `usernameOrEmail` | string | Accepts either username or email.                    |
| `password`        | string | User password exactly as stored (bcrypt on backend). |

#### Response

* `200 OK` – Same `AuthResponse` shape as signup.
* `401 Unauthorized` – Bad credentials (see `Error` schema for message).

#### Sample

```bash
curl -X POST "$API_BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"usernameOrEmail":"learner42","password":"super-secure"}'
```

### GET `/auth/me`

Return the authenticated user's profile.

#### Headers

`Authorization: Bearer <token>` – Required.

#### Response

* `200 OK` – `User` schema (id, username, optional email, created timestamp).
* `401 Unauthorized` – Missing/invalid token.

#### Sample

```bash
curl "$API_BASE_URL/auth/me" \
  -H "Authorization: Bearer $TOKEN"
```

> **Tip:** Keep the Swagger spec (`swagger.yaml`) in sync whenever you add new auth flows (password reset, guest tokens, etc.). That file powers the generated API docs.
