--- title: "Driver App authentication contract" description: "Understand configured sign-in branches, Driver role checks, and local session state." canonical: https://docs.ordering.co/docs/developers/driver-app/authentication-contract/ --- # 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](https://docs.ordering.co/docs/products/driver-app/get-started/open-driver-app/) · [Sign in as a driver](https://docs.ordering.co/docs/products/driver-app/get-started/sign-in/) · [Sign-in options](https://docs.ordering.co/docs/products/driver-app/get-started/sign-in-options/) · [Reset a password](https://docs.ordering.co/docs/products/driver-app/get-started/reset-password/) · [Authenticated bootstrap](https://docs.ordering.co/docs/developers/driver-app/authenticated-bootstrap/)