Skip to main content

Authentication & 2FA

Errora authenticates people by Iranian mobile number (09XXXXXXXXX, normalized from +98… / 0098… forms). Email exists as a contact field and an alert channel, not as a login.

The two-step sign-in​

  1. POST /auth/start with the number alone. The answer says whether the account exists, whether it has_password, and whether an otp_sent code went out.
  2. Then either:
    • POST /auth/login with number + password, or
    • POST /auth/otp/verify with number + the six-digit code (request another with POST /auth/otp/request).

An unknown number gets an account created at step 1. The account is provisioned — a personal organization plus signup credit — once the first sign-in completes.

An account with no password can only sign in by OTP, which is why codes are always available.

Tokens​

Sign-in returns a JWT access token and a refresh token:

Authorization: Bearer <access_token>
POST /auth/refresh    # exchange the refresh token for a new access token
POST /auth/logout
GET  /auth/me

For scripts, CI and MCP clients use a personal access token instead.

Set or change a password​

POST /auth/password

Or in the UI: Profile → Password. Setting one gives you the faster password path and is required before you can enable TOTP meaningfully.

Two-factor authentication (TOTP)​

Profile → Two-factor authentication:

POST /auth/totp/setup     # returns the secret / provisioning URI to scan
POST /auth/totp/enable    # confirm with a code from the app
POST /auth/totp/disable

Scan the QR with any authenticator app (Google Authenticator, Aegis, 1Password). After enabling, sign-in asks for the six-digit code as well as your password.

Keep a way back in: an authenticator lost with no recovery path means an admin has to disable TOTP for you on the server.

Troubleshooting​

SymptomCause / fix
"Code not received"Wait for the cooldown and request again; check that the number is a valid Iranian mobile
Password rejected but you're sureThe account may have no password set; use OTP, then set one in Profile
Number not recognizedIt is normalized to 09XXXXXXXXX — +98/0098 forms are accepted, landlines are not
Locked out by TOTPAn administrator must clear the TOTP secret on the account