#Authentication API

These are the endpoints behind monetr's sign-in screens. Registering, signing in, verifying an email address, resetting a forgotten password, and finishing a two-factor challenge.

#What's turned on depends on your config

Most of these endpoints return 404 when the feature behind them is disabled, rather than existing and failing. Worth knowing before you go looking for a bug:

Reset a password is the exception. It stays available even without SMTP, because the reset token is what secures it, and an operator can mint one from the command line on a deployment that deliberately has no mail server.

#POST Sign in

Exchanges an email and password for a session. What you get back depends on the state of the login: a working session, a demand for a TOTP code, a demand to verify your email, or a demand to change an expired password.

In the app: The login screen.

POST /api/authentication/login

Auth: None.

#Body

#Responses

On success, 200:

{
  "isActive": true
}

isActive reflects the subscription, and a nextUrl of /account/subscribe comes along with it when the subscription has lapsed. With billing disabled, isActive is always true.

The interesting responses all come back as 428, and each carries a code:

#Errors

#POST Finish two-factor sign-in

Second step for a login with TOTP enabled. Turns the short lived pending session from sign-in into a real one.

In the app: The two-factor code screen you land on after the login screen.

POST /api/authentication/multifactor

Auth: MFA pending. Only reachable with the short lived session sign-in just handed you, which is why an API key can't touch it.

#Body

Returns the same shape as a successful sign-in.

#Errors

#GET Sign out

Ends the session.

In the app: The sign out button.

GET /api/authentication/logout

Auth: None. It's a GET and it takes no body. Calling it without a session is fine, it does nothing and returns 200.

Returns 200 with an empty body.

#POST Register

Creates a login, an account, and the user joining them.

In the app: The sign-up form.

POST /api/authentication/register

Auth: None.

#Body

#Errors

#POST Verify an email address

Confirms an email address using the token from the verification email.

In the app: The page you land on from the link in the verification email.

POST /api/authentication/verify

Auth: None. The token is the credential.

#Body

{
  "nextUrl": "/login",
  "message": "Your email is now verified. Please login."
}

#Errors

#POST Resend a verification email

Sends the verification email again.

In the app: The resend link on the "check your email" screen.

POST /api/authentication/verify/resend

Auth: None.

#Body

#Errors

#POST Request a password reset

Emails a reset link to an address.

In the app: The forgot password form.

POST /api/authentication/forgot

Auth: None.

#Body

#Errors

#POST Reset a password

Sets a new password using a reset token.

In the app: The set-a-new-password form you reach from the reset email, and the same form after a sign-in that demanded a password change.

POST /api/authentication/reset

Auth: None. The token is the credential.

#Body

Unlike the other email-driven endpoints, this one stays available even when SMTP is off. The token is the security control, and an operator can generate one with the login:reset-password CLI command on a deployment that deliberately can't send mail.

#Errors