# Authentication & 2FA

> https://docs.errora.org/en/account/auth

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:

```text
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](/en/account/tokens) instead.

## Set or change a password

```text
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**:

```text
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

| Symptom | Cause / 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 sure | The account may have no password set; use OTP, then set one in **Profile** |
| Number not recognized | It is normalized to `09XXXXXXXXX` — `+98`/`0098` forms are accepted, landlines are not |
| Locked out by TOTP | An administrator must clear the TOTP secret on the account |