Authentication

Login

Authenticate as an Admin or BD account. Returns a role-based JWT valid for 24 hours.

POST /api/v1/broker/auth/admin/login
Content-Type: application/json

Rate limit: 1 req/s sustained, burst 5.

Request Body

{
  "username": "alice_bd",
  "password": "s3cur3pass"
}

Field	Type	Required	Description
username	string	Yes	BD or admin username
password	string	Yes	Plaintext password

Response

{
  "token": "eyJhbGci...",
  "role": "bd"
}

Field	Type	Description
token	string	JWT — include as Authorization: Bearer <token>
role	string	"admin" or "bd"

Errors

HTTP	Description
404	Invalid username or password

---

Bootstrap Admin

One-time endpoint to create the first admin account. Requires the BROKER_BOOTSTRAP_SECRET environment variable to be set on the server. Fails immediately if any admin already exists.

POST /api/v1/broker/auth/bootstrap
Content-Type: application/json

Request Body

{
  "username": "root",
  "password": "strongpassword",
  "display_name": "Root Admin",
  "secret_key": "bootstrap-secret-from-env"
}

Field	Type	Required	Description
username	string	Yes	Admin username
password	string	Yes	Plaintext password (bcrypt-hashed server-side)
display_name	string	No	Display name
secret_key	string	Yes	Must match BROKER_BOOTSTRAP_SECRET

Response

{
  "admin_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJhbGci..."
}

Errors

HTTP	Description
400	Admin already exists
403	Invalid bootstrap secret