Sayyarat Documentation

Public Docs

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

Public surfaceauth-spec.md

Identity, Authentication, and Authorization

Purpose

This document describes the public client-facing auth model for Sayyarat.

It covers:

  • who signs in
  • how browser and native clients stay signed in
  • which auth assumptions clients may rely on

It does not expose internal staff tooling or internal auth implementation detail.

---

Account Model

  • every person has one base account
  • seller capability is attached to that account
  • dealer access is attached through business membership
  • admin access is internal staff access and is not part of the public signup path

Clients should treat account_ref as the stable user-facing account reference.

---

Login Model

Current base login identity:

  • email
  • password

Browser and native clients share one backend identity model, but they do not have to use the same session transport.

---

Browser Auth

Browser auth uses a same-origin cookie session.

Client rules:

  • browser code should rely on the backend session, not local token storage
  • browser writes still require CSRF where the API expects it
  • browser clients should use the durable /v1/auth/* routes where available

---

Native And Non-Browser Auth

Native and non-browser clients should use:

  • bearer access token
  • refresh token flow

Client rules:

  • native clients must not depend on browser cookies
  • native clients must not depend on CSRF to stay signed in
  • browser-only session assumptions should not leak into iPhone or partner clients

---

Account States

Current public-facing account states:

  • pending_verification
  • active
  • suspended
  • deactivated

Important client rule:

  • seller activation requires a verified email

---

Authorization Rule

Authorization is explicit.

Clients should not infer elevated access from:

  • seller status
  • dealer membership alone
  • hidden UI entries

If a route is protected, the backend remains the source of truth.

---

Durable Auth Routes

Examples:

  • POST /v1/auth/signup
  • POST /v1/auth/login
  • POST /v1/auth/logout
  • GET /v1/auth/me
  • POST /v1/auth/native/login

Use the live API docs for the exact request and response schema.