Auth Flows
This page is the authoritative reference for authentication in Vruksha ERP: signup, email verification, login and lockout, password reset, user invitations, and token rotation — with the exact token lifetimes and rate limits the system enforces.
For who-can-do-what after login, see RBAC Matrix. For the user states referenced here, see Status Lifecycles → User.
At a glance
| Mechanism | Lifetime / limit | Single-use? |
|---|---|---|
| Email verification token | 24 hours | Yes |
| Password reset token | 24 hours (60s resend cooldown, max 5 per hour) | Yes |
| User invitation | 7 days | Yes |
| Login lockout | 5 failed attempts → 15-minute lockout | — |
| Access token (JWT) | Short-lived (15–30 min) | — |
| Refresh token | Long-lived, rotated on each refresh | — |
1. Signup → organization + first admin
Signing up creates a new organization and its first administrator in one step, then sends an email-verification link.
- The prospective owner submits organization details and their credentials.
- The system creates the
organizationand the firstuseras Admin for that organization. - An email verification token (valid 24 hours, single-use) is generated and emailed.
- The new account remains unverified / pending until the email is verified (and, per policy, admin approval where applicable).
2. Email verification (24h, single-use)
| Property | Value |
|---|---|
| Token lifetime | 24 hours |
| Reuse | Single-use — consumed on first successful verification |
| Resend | Subject to a 60-second cooldown and an hourly cap |
| Expired/used token | Verification fails; the user requests a fresh link |
After successful verification, the user transitions out of UNVERIFIED and can sign in.
3. Login + lockout (5 attempts / 15-minute lockout)
Login exchanges valid credentials for an access token (short-lived JWT, 15–30 minutes) and a refresh token (long-lived). Repeated failures trigger a lockout.
| Property | Value |
|---|---|
| Failed-attempt threshold | 5 consecutive failures |
| Lockout duration | 15 minutes |
| User state during lockout | LOCKED |
| On success | Failure counter resets; tokens issued |
Login decision flow:
4. Password reset (24h, single-use, 60s cooldown, 5/hour)
| Property | Value |
|---|---|
| Reset token lifetime | 24 hours |
| Reuse | Single-use |
| Resend cooldown | 60 seconds between requests |
| Hourly cap | Maximum 5 reset requests per hour |
| New password | Must satisfy the password policy |
To prevent account enumeration, the request-reset response does not reveal whether an email is registered. The token is invalidated immediately after a successful reset.
5. User invitations (7-day, single-use)
Administrators invite users into an existing organization. Invitations differ from email-verification and reset tokens in lifetime: they last 7 days.
| Property | Value |
|---|---|
| Invitation lifetime | 7 days |
| Reuse | Single-use — consumed on acceptance |
| Invited user state | INVITED until accepted |
| Expired invitation | Cannot be accepted; the admin re-sends a new invitation |
6. Token rotation on refresh
Sessions use a short-lived access token and a long-lived refresh token.
- The access token (JWT, 15–30 minutes) authorizes API calls. When it expires, the client uses the refresh token to obtain a new one.
- The refresh token rotates on every refresh: each refresh issues a new refresh token and invalidates the previous one. Re-use of an old (already-rotated) refresh token is rejected, which limits the value of a stolen token.
- Logout invalidates the session and clears authentication cookies.
Cookie & token security: authentication cookies are httpOnly, Secure, and SameSite. Access tokens are short-lived by design; refresh tokens are long-lived but single-use through rotation.
Quick reference: error outcomes
| Situation | Result |
|---|---|
| Expired or already-used verification/reset/invitation token | Rejected; request a fresh link/invitation. |
| 6th+ password-reset request within an hour, or within 60s of the last | Rejected by rate limit. |
| 5 consecutive failed logins | Account LOCKED for 15 minutes. |
| Reusing a rotated refresh token | Rejected; user must sign in again. |
| New password failing policy | Rejected with the policy requirement. |
Related: Validation Rules → Password policy, RBAC Matrix, and Status Lifecycles → User.