Verify MFA
Second step of an MFA-protected login. Call this only after /auth/login returns mfa_required: true. Re-sends the same credentials plus the six-digit TOTP code from the user's authenticator app and returns the same JWT shape /auth/login would have on a non-MFA account.
The endpoint is rate-limited per user: too many bad TOTP attempts trip the MFA rate limiter and lock further attempts for several minutes (separate from the password rate limiter on /auth/login).
Request body
username string Req
Same username used in the previous
/auth/login call.password string Req
Same password — the server re-verifies on every MFA submission so a stolen TOTP code alone can't grant access.
token string Req
Six-digit TOTP code from the user's authenticator (or a recovery code, if the platform allows them). Codes are valid for ~30s; a small clock-skew window is tolerated.
Response (200 OK)
success boolean
Always
true on a successful verification.access_token string
Signed JWT — same shape as /auth/login.
user object
Minimal user object:
id, username, email, role.Errors
400 Bad Request
Missing one of
username/password/token, or unknown fields (handler uses strict decoding).401 Unauthorized
Wrong password or wrong/expired TOTP code. Same generic "Invalid credentials" message used for either to prevent leaking which factor failed.
403 Forbidden
Email not verified (
code: "EMAIL_NOT_VERIFIED").429 Too Many Requests
MFA rate limit hit. Body says how many minutes until reset.
Request
curl -X POST "https://api.ngris.com/v1/auth/mfa" \
-H "Content-Type: application/json" \
-d '{
"username": "alice",
"password": "s3cur3p@ss!",
"token": "654321"
}'
Python
from ngris import Ngris
client = Ngris(api_key="placeholder")
resp = client.auth.mfa_verify(
username="alice",
password="s3cur3p@ss!",
token="654321",
)
print(resp.access_token)
Response — 200 OK
{
"success": true,
"access_token": "eyJhbGciOiJIUzI1NiI...",
"user": {
"id": 1024,
"username": "alice",
"email": "alice@example.com",
"role": "user"
}
}
Error — bad TOTP
Invalid credentials