Sayyarat Documentation

Public Docs

Client-safe integration guidance for API usage, auth, listing lifecycle, media, and search.

Public surface

Sessions And Security

Purpose

This page defines the session transport and safety rules for browser and native clients.

Browser Sessions

The web app uses secure cookies.

Locked rules:

  • FastAPI owns session issuance and validation
  • browser sessions use secure, HTTP-only cookies
  • browser sign-out invalidates the server-side session record
  • Redis is never the source of truth for identity or session state

Native Sessions

Native apps must not depend on browser cookies or CSRF to stay signed in.

Locked rules:

  • native and browser clients may use different transport
  • both must share one account model and one backend source of truth
  • native sessions must remain revocable from the server side

Verification And Recovery

The first identity safety flows are:

  • email verification
  • password reset

Locked rules:

  • both flows must use short-lived server-issued tokens
  • tokens must be one-time-use
  • token state must live in PostgreSQL
  • both flows must send people to repo-owned web pages first, even when the email is opened on a mobile device
  • request payloads may include a sanitized next_path so the post-email flow can return people to the right sign-in destination without exposing arbitrary redirects
  • request payloads may include return_target=ios when the shared web page should expose the iPhone handoff path
  • the web verification and reset pages remain the shared fallback-safe return surface for browser and native clients
  • when return_target=ios, verification and reset email links may hand off through:
    sayyarat://auth/verify-email?token=...&next=...
    sayyarat://auth/reset-password?token=...&next=...
    sayyarat://auth/login?next=...

Abuse Controls

Locked rules:

  • signup, sign-in, verification, and password-reset entry points must have server-side abuse controls
  • those thresholds are runtime security settings, not DB-backed marketplace rules
  • those thresholds must not be hidden as hardcoded request-path constants
  • normal admin UI should not control those security thresholds

Authorization Direction

Authorization should resolve from:

  • current session
  • account identity
  • seller profile state
  • business membership
  • admin grants

Authorization must not rely on client claims alone.

Anti-Patterns To Avoid

Do not:

  • treat Redis as the source of truth for session state
  • create separate buyer and seller login systems
  • encode durable authorization decisions only in the web app
  • build native auth as a parallel identity model