Driver App authentication contract
Driver App authentication combines configured credential branches, server authentication, a Driver-role gate, and local session persistence. Treat those as separate decisions: a successful credential response is not automatically a valid Driver session, and locally restored session state is not fresh server authorization.
The configured authentication service and provider determine whether a login request succeeds. The app must still enforce the Driver role and authorize each later API request.
Availability
The Login screen enables email and cellphone password presentation and passes the Driver role as its allowed standard-login role. Project configuration can also expose OTP, device-code, provider-specific, CAPTCHA, or other alternate branches. Alternate branches do not uniformly repeat the same Driver-role gate and must not be called equivalent without separate acceptance.
Signed-out navigation registers Home, Login, and Forgot. It does not register Driver signup or map inbound deep links.
Prerequisites
- A configured Driver App build and supported Driver account workflow.
- Current authentication configuration for the intended branch.
- Explicit Driver-role enforcement on every branch that can create local session state.
- Secure handling of credentials, OTP values, provider results, tokens, notification identity, and locally stored account data.
- Separate server authorization on every request after authentication.
Responsibility boundaries
| Boundary | Responsibility | Limit |
|---|---|---|
| Login UI | Present configured credential/OTP/provider controls and local validation/loading/error states. | Visibility does not prove provider or server availability. |
| Authentication controller | Build the selected credential shape, call the matching API endpoint, and interpret the response. | Branches can differ in role checks and cleanup. |
| Driver role gate | Admit only the Driver role into the standard local-session path. | Alternate branches may not apply the same check. |
| Rejected-role cleanup | Request server logout for a returned non-Driver session before showing permission error. | Logout/cleanup can fail or partially settle. |
| Session provider | Save/remove local token, user and optional device state; expose auth/loading. | Local storage is not server validation or revocation. |
| Root navigation | Select signed-out or authenticated branch from local session/readiness state. | Navigation is not authorization for a task. |
| API | Authenticate credentials and authorize every subsequent read/mutation. | Check the API behavior for the environment used by the app. |
| OTP/CAPTCHA/provider | Own generation, verification, challenges and external results. | Provider completion does not prove Driver role. |
Inputs and result
| Input/branch | Client result | Required check | Failure/partial boundary |
|---|---|---|---|
| Email/cellphone + password | Standard authentication response | Driver role before local login | Error, wrong role, cleanup failure, missing session |
| OTP | Generated/verified one-time credential result | Repeat Driver-role and session policy | Some verification paths can set local session without the standard role block |
| Device code | Device-code credential and optional local persistence | Driver role, device ownership and revocation | UI exposure differs from controller capability |
| Provider-specific login | Provider/server result | Driver role and provider identity | Availability and role parity unproven |
| CAPTCHA | Challenge value added before selected request | Challenge validity and provider result | Missing/incomplete config can block or distort another branch |
| Notification identity | Optional token/app data included during authentication | Notification ownership and privacy | Login success does not prove push registration/delivery |
| Local session restore | Stored token/user/device returned to providers | Reauthorize each API request | Stale/disabled/wrong-role state can persist until later checks |
| Forgot flow | Local form can show a link-sent state before request settlement | Observe final success/error separately | UI transition is not delivery or reset completion |
Security and privacy
- Never log or expose credentials, OTP, CAPTCHA values, tokens, provider IDs, notification identity, account records, or device codes.
- Apply the Driver-role gate before every branch writes local session state.
- Treat rejected-role logout, provider cleanup, token revocation and local cleanup as separate results.
- Do not inject tokens, navigate directly to authenticated routes, or treat saved state as proof of authorization.
- Clear prior-account and late-request state before admitting another account.
Limits and failure states
| State | Meaning | Maintainer response |
|---|---|---|
| Configured branch hidden | UI/config does not admit it. | Do not expose controller-only capability. |
| Authentication error | Selected server/provider contract returned or threw failure. | Keep session signed out and surface sanitized error. |
| Wrong role | Standard branch rejected returned account. | Require complete server/local cleanup; no authenticated navigation. |
| Alternate branch success-looking | Provider/OTP returned an account/session. | Verify Driver-role parity before local login. |
| Local session restored | Saved data became available. | Reauthorize every read/action; do not call it fresh. |
| Disabled/missing local user | Session consistency check can request local logout. | Server state and cleanup remain separate. |
| Forgot link-sent state | Local recovery UI advanced. | Await actual request/result; no email-delivery claim. |
Troubleshooting
| Symptom | Inspect | Safe diagnostic |
|---|---|---|
| Expected sign-in option is missing | Current configuration and UI exposure | Do not invoke a controller-only branch. |
| Non-Driver account appears accepted | Branch-specific role enforcement and local session write | Stop authenticated work and follow secure cleanup/escalation. |
| Wrong-role error appears but state is unclear | Server logout, local session and navigation results separately | Do not reuse returned tokens or force navigation. |
| App opens authenticated from saved state | Session hydration and per-request authorization | Treat stored state as provisional until current requests authorize. |
| Recovery says link sent too early | Local transition versus request settlement | Wait for final error/success; do not repeat or claim delivery. |
Re-review this contract whenever a login branch, role gate, CAPTCHA/provider, notification identity, session storage, rejected-role cleanup, recovery state or Root auth selection changes.
Related guides: Open Driver App and reach sign in · Sign in as a driver · Sign-in options · Reset a password · Authenticated bootstrap