# SeaHaven Dev Postman starter

A small, versioned Postman starter for the SeaHaven backend **dev** API.

- The **live OpenAPI document** (`{{baseUrl}}/swagger/v1/swagger.json`) is the
  complete source of truth for routes and schemas. This committed collection is
  a curated starter — it is **not** a generated copy of the full API surface.
- **Dev only.** Never point these requests at any other environment.

## Files

| File | Purpose |
| --- | --- |
| `SeaHaven-Dev.postman_collection.json` | Starter collection: setup requests plus safe read-only requests |
| `SeaHaven-Dev.postman_environment.json` | Dev environment: `baseUrl` plus empty secret `username` / `password` / `token` |

## Getting started

1. **Import order** — collection first, then environment:
   1. Postman → Import → `postman/SeaHaven-Dev.postman_collection.json`
   2. Postman → Import → `postman/SeaHaven-Dev.postman_environment.json`
2. **Select the environment** — pick `SeaHaven - Dev` in the environment picker
   (top right of Postman).
3. **Fill credentials locally** — open the environment and enter values for
   `username` and `password`. They ship empty and marked secret on purpose;
   keep them local to your Postman workspace.
4. **Run login** — run `Authentication - Login` in the `Setup` folder once. A
   successful (200) response captures the bearer token automatically. Every
   login attempt clears the previous token value without deleting the variable,
   so a failed login cannot leave stale authentication active.
5. **Use the safe reads** — everything in the `Safe reads` folder inherits the
   collection-level `Bearer {{token}}` auth, so no extra setup is needed.

## Token capture behavior

The login test script stores the returned bearer token **only** in the
environment variable `token` via `pm.environment.set("token", token)`. It never
writes collection or global variables and never prints credentials or tokens to
the Postman console. The pre-request script skips the request and stops with a
clear message if `username` or `password` is empty.

**Clearing the token:** open `Environments → SeaHaven - Dev`, clear the `token`
value (or use the environment reset), and save. Do this before sharing screens,
exporting, or switching machines.

## Safety rules

- Keep populated `username`, `password`, and `token` values local. **Never mark
  them shared, export them, or commit them.**
- **Never save dev response bodies as collection examples or commit them.**
- **Full API surface:** in Postman, choose **Import → Link** and paste
  `https://api.dev.seahaven.com/swagger/v1/swagger.json`. The `Swagger - OpenAPI
  document` request is also available to check that the contract is reachable.
- **Canonical routes:** some legacy aliases may still resolve on dev, but this
  collection sticks to canonical routes — prefer those when adding requests.