Authentication

Password login establishes a session using an HttpOnly auth_token cookie. A successful login response does not contain an accessToken field. With MFA enabled, login returns a pending challenge before a full session is issued.

Sign in#

Send POST /api/auth/login with these JSON fields:

Without MFA, success returns message and user and sets the cookie. With MFA, it returns mfa_required: true and mfa_pending_token. HTTP 200 alone does not establish that MFA is complete.

These are alternative clients. Keep the same cookie store throughout the flow.

For curl, set MANTRAWORX_URL to your HTTPS host without a trailing slash. Prepare a private login.json with your own email and password using the fields above, and set COOKIE_JAR to a private writable file. Keep both files out of source control and shared logs. Remove the password file when no longer needed.

curl --fail-with-body --cookie-jar "$COOKIE_JAR" \
  --header "Content-Type: application/json" \
  --data-binary @login.json \
  "$MANTRAWORX_URL/api/auth/login"

Run this function on the MantraWorx origin, supplying credentials from your form.

async function signIn(email, password) {
  const response = await fetch("/api/auth/login", {
    method: "POST",
    credentials: "same-origin",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });
  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.message ?? result.error ?? "Sign-in failed");
  }
  return result; // Complete MFA when mfa_required is true.
}

For Python, install requests, set MANTRAWORX_URL and retain this session for later calls.

import os
from getpass import getpass
import requests

base_url = os.environ["MANTRAWORX_URL"].rstrip("/")
session = requests.Session()
response = session.post(
    f"{base_url}/api/auth/login",
    json={"email": input("Email: "), "password": getpass("Password: ")},
    timeout=30,
)
response.raise_for_status()
login = response.json()
if login.get("mfa_required"):
    challenge = session.post(
        f"{base_url}/api/mfa/challenge",
        json={
            "mfa_pending_token": login["mfa_pending_token"],
            "token": getpass("Authenticator code: "),
        },
        timeout=30,
    )
    challenge.raise_for_status()

Complete MFA#

Send POST /api/mfa/challenge with mfa_pending_token and one of these fields:

Request an email code through POST /api/mfa/email-otp/send with mfa_pending_token, then send the received code to the challenge endpoint. Follow the server's resend delay.

A successful challenge returns user and sets the full session cookie. The pending token is single-use. Restart login if it expires or has already been redeemed.

Verify and use the session#

Call GET /api/auth/me and check the intended account. Reuse the login cookie store.

For same-origin browser calls, use credentials: "same-origin". Cross-origin use also requires an allowed origin and compatible cookie settings; credentials: "include" alone does not bypass browser restrictions.

The server can accept an Authorization: Bearer credential in supported contexts. This does not mean password login issues a bearer credential in its response body.

Sign out#

Send POST /api/auth/logout with the session cookie. It revokes the presented session credentials and clears the cookie. Stop using the local cookie store after logout.

Diagnose a failed login#

The endpoint defaults to 20 failed attempts per 15 minutes for the same address and email. Separate account and MFA protections also apply. Follow the actual response rather than assuming a fixed waiting period.

Password endpoints#

For user-facing steps, read Signing in and access.