jackboxpartypack-gamepicker/docs/api/endpoints/auth.md

# Auth Endpoints

Simple admin-key authentication. Single role (admin). No user management. Obtain a JWT from `POST /api/auth/login` and use it as a Bearer token for protected endpoints.

## Endpoint Summary

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/auth/login` | No | Exchange admin key for JWT |
| POST | `/api/auth/verify` | Bearer | Validate token and return user info |

---

## POST /api/auth/login

Exchange an admin key for a JWT. Use the returned token in the `Authorization: Bearer <token>` header for protected routes. Tokens expire after 24 hours.

### Authentication

None. This endpoint is public.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| key | string | Yes | Admin key (configured via `ADMIN_KEY` env) |

```json
{
  "key": "your-admin-key"
}
```

### Response

**200 OK**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "Authentication successful",
  "expiresIn": "24h"
}
```

| Field | Description |
|-------|-------------|
| token | JWT to use in `Authorization: Bearer <token>` |
| message | Success message |
| expiresIn | Token lifetime |

### Error Responses

| Status | Body | When |
|--------|------|------|
| 400 | `{ "error": "Admin key is required" }` | `key` field missing |
| 401 | `{ "error": "Invalid admin key" }` | Wrong key |

### Example

```bash
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"key": "your-admin-key"}'
```

**Sample response:**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJ0aW1lc3RhbXAiOjE3MTAwMDAwMDAwLCJpYXQiOjE3MTAwMDAwMDB9.abc123",
  "message": "Authentication successful",
  "expiresIn": "24h"
}
```

---

## POST /api/auth/verify

Verify that the provided Bearer token is valid and return the decoded user payload.

### Authentication

Bearer token required. Include in header: `Authorization: Bearer <token>`.

### Parameters

None.

### Response

**200 OK**

```json
{
  "valid": true,
  "user": {
    "role": "admin",
    "timestamp": 1710000000000
  }
}
```

| Field | Description |
|-------|-------------|
| valid | Always `true` when token is valid |
| user.role | User role (always `"admin"`) |
| user.timestamp | Unix ms when token was issued |

### Error Responses

| Status | Body | When |
|--------|------|------|
| 401 | `{ "error": "Access token required" }` | No `Authorization` header or Bearer token |
| 403 | `{ "error": "Invalid or expired token" }` | Bad or expired token |

### Example

```bash
curl -X POST http://localhost:5000/api/auth/verify \
  -H "Authorization: Bearer $TOKEN"
```

**Sample response:**

```json
{
  "valid": true,
  "user": {
    "role": "admin",
    "timestamp": 1710000000000
  }
}
```