Skip to content

Latest commit

 

History

History
82 lines (65 loc) · 4.09 KB

api.md

File metadata and controls

82 lines (65 loc) · 4.09 KB

API Reference

Base URL: https://{api-id}.execute-api.{region}.amazonaws.com (stage is part of the domain for HTTP API default stage $default).

All authenticated routes require Authorization: Bearer <Cognito ID token>. Roles are enforced two ways: API Gateway's JWT authorizer confirms the token is valid and attaches claims (including cognito:groups); each Lambda additionally checks the specific group/ownership rule noted below (defense in depth — a misconfigured route scope shouldn't be the only thing standing between a User and an Admin action).

Auth — /auth/* (public)

Thin wrappers around Cognito so the client only ever talks to one API.

Method Path Body Notes
POST /auth/signup { email, password, name, role } role ∈ USER, ORGANIZER. Admins are seeded out-of-band (see scripts/seed-admin.ts), never self-service.
POST /auth/confirm-signup { email, code } Confirms the emailed verification code.
POST /auth/login { email, password } Returns idToken, accessToken, refreshToken.
POST /auth/refresh { refreshToken, email } Returns a new idToken/accessToken pair.
POST /auth/forgot-password { email } Triggers Cognito's reset-code email.
POST /auth/reset-password { email, code, newPassword }

Contact — /contact (public)

Method Path Body Notes
POST /contact { name, email, message } Publishes CONTACT_MESSAGE_RECEIVED → emails the team, with the sender set as reply-to. Throttled the same as /auth/*. Returns 202 { received: true }.

Events — /events/*

Method Path Auth Notes
POST /events Organizer Creates event, status = PENDING_REVIEW.
GET /events Public Lists APPROVED upcoming events. Query: category, from, to, limit, cursor.
GET /events/{eventId} Public Event detail. PENDING_REVIEW/REJECTED events are hidden from non-owners.
PUT /events/{eventId} Organizer (owner) Editing a non-PENDING_REVIEW event resets it to PENDING_REVIEW for re-approval (prevents bait-and-switch after approval).
DELETE /events/{eventId} Organizer (owner) or Admin Soft delete — sets status = CANCELLED, does not remove history.
GET /organizers/me/events Organizer Own events, any status. Query: status.

Registrations & Ticketing — /events/{eventId}/register, /users/me/registrations

Method Path Auth Notes
POST /events/{eventId}/register User Fails with 409 if already registered, event full, or event not APPROVED/in the future. Publishes REGISTRATION_CONFIRMED → confirmation email with ticket link.
DELETE /events/{eventId}/register User (self) Cancels own registration, decrements registeredCount.
GET /users/me/registrations User Own registration history.
GET /events/{eventId}/registrations Organizer (owner) or Admin Roster for an event.

Admin — /admin/*

Method Path Auth Notes
GET /admin/events Admin Query status (defaults to PENDING_REVIEW).
POST /admin/events/{eventId}/review Admin { decision: "APPROVED" | "REJECTED", reason? }. reason required when rejecting. Publishes EVENT_REVIEWED → organizer email.
GET /admin/users Admin Query role.
PATCH /admin/users/{userId}/role Admin { role: "ORGANIZER" | "USER" } — promote/demote (not usable to grant ADMIN).

Error shape

All errors return a consistent JSON body so the frontend can render them uniformly:

{
  "error": {
    "code": "EVENT_NOT_APPROVED",
    "message": "Cannot register for an event that has not been approved."
  }
}
HTTP When
400 Validation failure (Zod schema)
401 Missing/invalid JWT
403 Valid JWT, wrong role or not the resource owner
404 Resource not found
409 Conflict (duplicate registration, event full, capacity race lost)
500 Unhandled — logged with a correlation id via CloudWatch/X-Ray