Sign in with username and password

POST

/auth/login

• Local development behind nginx (port 8088 by default)

Verifies credentials against the RS user table using the same HMAC-then-bcrypt hashing scheme RS uses (so PHP-created users log in unchanged). On success: writes a new session token to user.session and sets the rs_session cookie.

Request Body ^required

object

username

required

string

Example

admin

password

required

string format: password

provider

Name of the identity provider to authenticate against. Defaults to “password” (the built-in flow). Enterprise installs can name a registered LDAP provider (“ldap” or a per-server alias like “ldap-engineering”). Requests naming an unregistered provider get 401 — same shape as a bad password, so a probing client can’t enumerate which enterprise providers are active.

string

Example

password

totp_code

TOTP code (6 digits) or recovery code (10 chars + optional hyphen) for users with 2FA confirmed. When 2FA is enabled and this field is missing or wrong the server returns 401 with error: "2fa_required" (no totp_code on the request) or error: "invalid_2fa_code" (wrong code) so the frontend can re-prompt.

string

Responses

200

Authenticated. Returns the current user; an rs_session cookie is set in the response headers.

object

ref

required

integer format: int64

username

required

string

fullname

string

nullable

email

string

nullable

usergroup

integer format: int64

nullable

auth_method

required

How the caller was authenticated for this request.

string

Allowed values: session token

language

User’s language pref (BCP47). Empty string = follow system / browser. Joined from user_profiles at /auth/me time so the frontend can hydrate the language store on first paint without a separate round-trip.

string

theme

User’s theme pref. Empty string = follow system. Same “join on /auth/me” rationale as language.

string

Allowed values: "" light dark

impersonated_by

Non-null when the session was minted via POST /admin/users/{ref}/impersonate. Carries the acting admin’s ref + username so the persistent “you are acting as @target” banner can render without a separate round-trip.

object

ref

required

integer format: int64

username

required

string

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed

501

Identity provider was registered (license includes its feature flag) but the credential-verification impl has not yet landed in this binary. Distinct from 401 so the admin UI can render “build pending” vs “wrong password”.

object

error

required

Human-readable error summary

string

Example

the request could not be completed