Auth (bootstrap)

Two-step bootstrap on first connection — reset the factory password, then obtain a short-lived Bearer token used by every other endpoint in this spec. These two endpoints carry no Bearer themselves and are rate-limited at 5/min/IP.

The on-appliance Broker API is available on Broker VM version 32 and later. Ubuntu-based brokers do not support this API.

Replace the factory-default admin password

post

Replace the broker's factory-default admin password with one of the operator's choosing. This is the first call that must succeed against a freshly-provisioned broker — every other endpoint (including generateToken) is blocked by InitialPasswordGateMiddleware until this returns 200.

• Authentication: the factory default password is the credential. No Bearer token is required.
• Rate limit: 5 requests per minute per source IP.
• Idempotency: not idempotent — the second call with the factory password returns 403 (PasswordAlreadyReset) because the password is no longer the factory default.
• Password policy: structural minimum is one character; Django's AUTH_PASSWORD_VALIDATORS enforce strength rules and emit 400 with the full validator error chain.

Body

Body for resetInitialPassword. The current_password must match the factory default; the new_password is validated against Django's password policy server-side.

current_passwordstring · password · min: 1Required

The factory-default admin password.

new_passwordstring · password · min: 1Required

New admin password. Structural minimum is one character; Django's AUTH_PASSWORD_VALIDATORS enforce real strength rules and surface their failures as 400.

Responses

200

Password successfully replaced. Proceed to generateToken.

application/json

Canonical envelope for every successful (2xx) JSON response. Wraps the per-endpoint payload (or null when the operation carries no body content).

replyany · nullableOptional

Endpoint-specific payload. Schema varies; see each operation's 200.content.schema.

400

Request body failed Pydantic validation, or the proposed new password failed Django's password validators.

application/json

401

current_password does not match the stored factory password.

application/json

403

Initial password has already been reset on this broker.

application/json

429

Caller exceeded the per-IP rate limit on this endpoint (5/min on the two bootstrap endpoints, 1/sec on the six network endpoints).

application/json

post/public_api/v1/auth/reset-initial-password

POST /public_api/v1/auth/reset-initial-password HTTP/1.1
Host: broker.example.local
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "current_password": "FactoryDefault!",
  "new_password": "NewStrongPassw0rd!"
}

{
  "reply": null
}

Obtain a 10-minute Bearer token

post

Authenticate with the admin password and receive a short-lived opaque API token (TTL 10 minutes) used to call every other endpoint in this spec. The token is returned once — store it immediately.

• Authentication: the password in the body is the credential; no Bearer required.
• Rate limit: 5 requests per minute per source IP.
• Gating: requires resetInitialPassword to have already succeeded (otherwise 403).
• Token lifetime: 10 minutes from issuance, not from last use. To renew, call this endpoint again.

Body

Body for generateToken. The password is the current admin password (post-reset).

passwordstring · password · min: 1Required

Current admin password (set via resetInitialPassword).

Responses

200

Token issued.

application/json

Success envelope for generateToken.

400

Pydantic validation failure (missing or empty password).

application/json

401

Authentication failed.

application/json

403

Either the initial password has not been reset (call resetInitialPassword first), or the supplied password is still the factory default.

application/json

429

Caller exceeded the per-IP rate limit on this endpoint (5/min on the two bootstrap endpoints, 1/sec on the six network endpoints).

application/json

post/public_api/v1/auth/token

POST /public_api/v1/auth/token HTTP/1.1
Host: broker.example.local
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "password": "NewStrongPassw0rd!"
}

{
  "reply": {
    "api_key": "<short-lived-bearer-token>"
  }
}