Auth
Authentication management. Direct source runs may be passwordless; shipped Compose deployments require first-password setup.
GET /auth/status
Section titled “GET /auth/status”Check authentication status
Returns whether password protection is enabled and if the current session is authenticated. This endpoint is always accessible without authentication.
No session needed.
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Authentication status | object |
200 response body
Section titled “200 response body”passwordSet(boolean): Whether a password is configuredauthenticated(boolean): Whether current session is authenticated
POST /auth/login
Section titled “POST /auth/login”Login with password
Authenticate with the configured password. Rate limited to 3 attempts per minute and 10 attempts per hour.
No session needed.
Request body (application/json, required)
Section titled “Request body (application/json, required)”password(string, required): The application password
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Login successful | object |
| 401 | Invalid password | Error |
| 503 | Authentication is required but the first password has not been set | Error |
200 response body
Section titled “200 response body”authenticated(boolean)message(string)
POST /auth/logout
Section titled “POST /auth/logout”Logout and clear session
Clears the current session. An authenticated logout requires the CSRF cookie/header pair; an unauthenticated caller may clear stale state.
No session needed.
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Logout successful | object |
| 403 | Missing or invalid CSRF token for an authenticated session | Error |
200 response body
Section titled “200 response body”authenticated(boolean)message(string)
PUT /auth/password
Section titled “PUT /auth/password”Set or change password
Set or change the application password. Rate limited to 3 attempts per hour.
- Initial setup is allowed from loopback. When required auth is on, remote setup needs the configured value in X-MinusPod-Setup-Token.
- An existing password requires currentPassword instead of CSRF.
- A new or changed password rotates the session generation, revokes every older session, and authenticates this request’s new session.
- Empty or null newPassword removes protection and clears this session.
- A non-empty newPassword must contain at least 12 characters.
No session needed.
Parameters
Section titled “Parameters”X-MinusPod-Setup-Token(header, string): Required only for remote initial setup when required auth is enabled.
Request body (application/json, required)
Section titled “Request body (application/json, required)”currentPassword(string): Current password (required if password is already set)newPassword(string or null, required): New password (at least 12 characters, or empty/null to remove protection)
Responses
Section titled “Responses”| Status | Description | Body |
|---|---|---|
| 200 | Password updated successfully | object |
| 400 | Invalid request (password too short) | Error |
| 401 | Current password incorrect | Error |
| 403 | Remote initial setup token missing or invalid | Error |
| 409 | Password changed concurrently; retry with current state | Error |
200 response body
Section titled “200 response body”message(string, required)passwordSet(boolean, required)