​
API authentication

SellTraces has two user authentication modes for public API routes.

​
Bearer tokens

CLI and machine clients authenticate with: 
Authorization: Bearer <token>
Bearer tokens can come from:

​
Browser session cookies

Browser flows authenticate with the Better Auth session cookie: 
better-auth.session_token=<session>
Dashboard pages, upload pages, and browser-driven API calls use this session path.

​
Auth modes by endpoint

Auth modeMeaning
nonePublic route or pre-auth flow
cookieSigned-in browser session required
bearerMachine bearer token required
cookie-or-bearerEither a signed-in browser session or bearer token

​
Device login endpoints

Start a device login: 
POST /api/cli/device/start
Content-Type: application/json

{
  "machine": "michaels-macbook"
}
Poll until the browser approval completes: 
GET /api/cli/device/poll?deviceCode=<deviceCode>
Pending polls return 202; approved polls return 200 with a bearer token. Check the current authenticated CLI session: 
GET /api/cli/session
Authorization: Bearer <token>
Valid sessions return 200 with the authenticated userId; missing or expired credentials return 401.

​
Better Auth delegation

/api/auth/{path} is delegated to Better Auth. SellTraces owns the mount and route coverage, while Better Auth owns the internal auth sub-route contracts. Generated reference pages cover the GET delegate and POST delegate.