Appearance
Login & Registration
EaseLab supports self-service lab registration, email verification, password recovery, and secure session management for both the tenant portal and platform admin portal.
Registration flow
New labs register through POST /auth/register:
| Field | Required | Notes |
|---|---|---|
labName | Yes | Display name; used to generate a URL slug |
email | Yes | Becomes the tenant owner account |
password | Yes | Must meet password policy |
firstName, lastName | No | Owner profile |
phone | No | Contact number |
After registration:
- If email verification is required, the API returns
requiresEmailVerification: true. - The user verifies via OTP (
POST /auth/verify-email-otp) or email link (POST /auth/confirm-email). - On success, access and refresh tokens are issued.
Registration email domains can be restricted by the platform — see Registration Policy.
Login flow
POST /auth/login accepts email and password.
| Response flag | Meaning | Next step |
|---|---|---|
requiresEmailVerification | Email not confirmed | Complete verification |
requiresTwoFactor | 2FA enabled | POST /auth/verify-2fa |
Normal AuthResponse | Success | Use access token; refresh cookie set automatically |
Blocked sign-in scenarios
| Condition | Message |
|---|---|
| Invalid credentials | Invalid email or password. |
| Unverified email | Verify your email before signing in. |
| Suspended/inactive tenant | Tenant lock reason or default inactive message |
| Rate limit exceeded | HTTP 429 |
Session tokens
| Token | Storage | Lifetime |
|---|---|---|
| Access token (JWT) | Client memory / Authorization header | 15 minutes |
| Refresh token | HTTP-only cookie refresh_token | 7 days |
Refresh with POST /auth/refresh (cookie sent automatically). Logout with POST /auth/logout, which revokes the refresh token server-side.
See API Authentication for JWT claims and endpoint details.
Password recovery
| Endpoint | Purpose |
|---|---|
POST /auth/forgot-password | Sends reset link if email exists (always returns success to prevent enumeration) |
POST /auth/reset-password | Sets new password with token from email |
Both endpoints are rate-limited.
Lab slug preview
Before registering, the UI can call GET /auth/lab-slug-preview?labName=... to show the proposed portal URL (e.g. my-lab → https://portal.example.com/my-lab).
Mobile authentication
Mobile apps use POST /auth/mobile/login and related endpoints. Refresh tokens are returned in the response body instead of cookies.
Portal URLs
| Portal | Typical URL | Auth route prefix |
|---|---|---|
| Tenant (lab) | https://app.example.com | /auth |
| Platform admin | https://admin.example.com | /auth |
Best practices
- Enforce two-factor authentication for tenant owners and admins.
- Use strong, unique passwords for each staff account.
- Revoke access promptly when staff leave — see Manage Roles.
- Never share impersonation links; they expire in 2 minutes.