API contracts, ownership & decisions

How to use this doc

Use this in a blame discussion. Classify the layer first. Then quote the row.

Shared request shape

All HTTP calls share one shape. Host and JWT signing secret come from the selected client in src/config/clients.ts.

Field	Value
Method	POST
ADNEC host	`https://registration.xporience.com/v2/scan/api`
DMG host	`https://dmg-reg.xporience.com/v2/scan/api`
Xporience host	`https://reg.xporience.com/v2/scan/api`
Terrapinn host	`https://terrapinn.xporience.com/v2/scan/api`
Body	`{ "operation": "<name>", "EPTOKEN": "<HS256 JWT>" }`
Headers	`Content-Type: application/json` · `Accept: application/json` · `User-Agent: AccessControlApp/1.0 (ReactNative)` · `Authorization: Bearer <AsyncStorage userToken>` (usually empty — see architecture)
Timeout	10s default · generateLead scan uses 3s

JWT is signed on the device with the active client’s secretKey via getSecretKeyFromClientId / getActiveSecretKey(). Xporience uses a different secret from ADNEC / DMG / Terrapinn. Do not paste secrets into tickets or this site.

Contract: userLogin

Mobile sends (JWT claims): username, password, device_id

Backend is expected to return

HTTP / body code	Meaning mobile implemented	Mobile owns	Backend owns
200 + `data`	Session fields: `user_id`, `event_id`, `event_name`, `timezone`, `excel_security_password`, email fields, `event_theme_color`, `silent_mode`, …	Persist user; null space until selection	Authentication; payload accuracy
400	Show `message`	Display	Validation
401	Show `message` (e.g. Invalid Data)	Display	Auth / payload rejection
409	Device/session conflict; clear unused `userToken`	Display + stay logged out	Session uniqueness
500	Sanitized user message	Sanitization	Server
Timeout / network	Connection copy	Detect Axios codes	Infra / device

Mobile does not own: whether the password is correct.

Do not log: username+password JWT payload, raw password, raw secret.

Contract: getSpaceList

Mobile sends (JWT claims): event_id, device_id

Result	Mobile owns	Backend owns
200 list of spaces (`space_id` / `space_name`, `type`, `assigned_badges`, event fields)	Render, search, write selected space onto session	Which spaces exist for this event/device
Empty / invalid rows	Empty/error UI	Data quality

No pagination found in mobile.

Contract: generateLead

Mobile sends (JWT claims): badge_number, event_id, badge_type (Visitor | Conference), visited_date, sync_date, user_id, space_id, device_id

Success body mobile reads: data.sync_status — only 1 counts as valid. Missing field = restricted on Home path.

Status (Home laser)	Mobile action	Mobile owns	Backend owns
200/201 + sync_status 1	Save online Valid	Persist + UI success	Badge allowed for this space/event
200/201 + sync_status ≠ 1	No save, Restricted	UI	Eligibility
801	No save, “Select another Space”	UI	Space service rule
403	No save, Restricted	UI	Access rule
404	No save, invalid badge	UI	Badge existence
409	Logout	Clear session	Device session revoked
400, 401, 405, 407, 408, 5xx, timeout	Save offline (Home)	Queue so gate continues	Availability / auth / timeout
503	Not handled on Home (camera/sync treat 503 as special)	—	Must confirm actual code

If backend returns 503 and mobile Home path does not recognize it, Home may fall through to “other 5xx → save offline”. Camera may not save. That is a contract bug, not “mobile being random.”

Ownership matrix (behaviors, not endpoints)

Behavior	Mobile owns	Backend owns	Device / Gmail owns
Client picker host + secret	Yes (`clients.ts`)	Provide correct URL/secret per env	—
Request shape, JWT claims, timeouts	Yes	Document the expected claims	—
HTTP status and `message` / `sync_status`	Interpret per matrix	Produce them	—
Local duplicate-today (Visitor)	Yes	May also reject duplicates	—
Offline queue	Yes	Accept delayed `visited_date`	—
Space eligibility (801/503)	Display	Rule	—
Excel contents	Yes (from local arrays)	Not involved	Filesystem
Email delivery	Attach + open composer	Email addresses in login payload	Mail app
Zebra scan hardware	Intent wiring	—	DataWedge profile
“Successfully Checked in” on timeout	Yes — documented fallback	Did not store the lead	—

Sentence: A 500 with “Saving offline” is mobile doing its job. A 404 “Invalid badge” is backend doing its job. A 200 with no sync_status showing Restricted is the contract (decideSuccessValidity).

Decision log (why this way)

Add a row when a behavior is chosen on purpose. Do not argue undocumented history.

ID	Date	Decision	Why (from code / known event needs)	Owner	Status
DEC-001	unknown	Single POST URL, `operation` discriminator	Matches existing registration scan API	Backend+mobile	In code
DEC-002	unknown	Client-signed EPTOKEN instead of server session bearer	Every request is a self-contained JWT. `userToken` / interceptor unused	Intent unconfirmed	In code; secret in client
DEC-003	unknown	Offline queue in Redux persist	Gate must not stop when Wi-Fi dies	Mobile	In code
DEC-004	unknown	Success toast for offline save	Queue speed over “honest sync state” in the toast	Mobile	In code — explain this in incidents
DEC-005	unknown	Logout keeps badge vault	Same device, multiple staff accounts, don’t wipe scans	Mobile (`HomeScreen` success copy)	In code
DEC-006	unknown	Visitor local re-checkin vs Conference always new	`type === '1'` vs other	Confirm with product	In code
DEC-007	unknown	Space change blocked until current-space queue syncs	Avoid mixing unsynced leads under the wrong space	Mobile	In code
DEC-008	unknown	Reports from device memory, email via Gmail	No report API	Mobile	In code
DEC-009	unknown	Excel/admin actions gated by login `excel_security_password`	Backend issues the password	Backend issues; mobile enforces	In code
DEC-010	unknown	Home counts derived from arrays, not `totalCount`	Counters drifted historically	Mobile HomeScreen	In code; other screens still use counters
DEC-011	unknown	Scan upload timeout 3s then offline	Fast scan lane	Mobile `SCAN_UPLOAD_TIMEOUT_MS`	In code
DEC-012	unknown	Restricted / invalid not queued on Home	Don’t inflate Excel with known-bad badges	Mobile NO_SAVE_CODES	In code
DEC-013	unknown	Two scan engines (Home vs camera)	Camera screen not refactored onto `processBadgeScan`	Not a decision — a risk	See risks
DEC-014	2026-08-19	Runtime client picker (ADNEC / DMG first)	One APK for multiple backends. Persist `selectedClientId`. Switch only while logged out. Unsynced queue for the client being left must sync or be wiped. Scans tagged `client_id`; untagged legacy rows are DMG.	Mobile	In code
DEC-015	2026-09	Add Xporience + Terrapinn clients	Same picker model; per-client `baseUrl` + `secretKey` in `clients.ts`. Xporience secret differs from shared ADNEC/DMG/Terrapinn secret.	Mobile	In code
DEC-016	2026-09	Fixed `User-Agent: AccessControlApp/1.0 (ReactNative)`	Some hosts (notably `reg.xporience.com`) returned HTML 403 to default OkHttp UA; custom UA reaches JSON API.	Mobile	In code

When you add DEC-017+, write the reason in one sentence. “Because backend said so” needs a meeting note or ticket id in the incident log.

Meeting decisions (living)

Date	Decision	Who	Evidence
—	(add rows here; do not create a 12th folder)

Dependencies that affect ownership

Dependency	If it fails, who looks first
`dmg-reg.xporience.com`	Backend / infra (DMG)
`registration.xporience.com`	Backend / infra (ADNEC)
`reg.xporience.com`	Backend / infra (Xporience)
`terrapinn.xporience.com`	Backend / infra (Terrapinn)
Event Wi-Fi / `isInternetReachable`	Device + venue network
Google `generate_204` ping used by Home `useNetworkStatus`	Device DNS/firewall (can mark offline while API still works, or the reverse after 10s debounce)
Zebra DataWedge	Device MDM / `dataWedgeConfig.ts`
Gmail / `react-native-mail`	Device mail setup
redux-persist / AsyncStorage	Mobile persistence

Diagnostics (recommended, not built yet)

Internal screen, not for operators: environment, app version, API base URL, selected client, user_id, space_id, online flag, last operation, last HTTP status, last message, last sync_status, duration, timestamp, copy/export.

Never log: passwords, EPTOKEN, Authorization, excel password, JWT secrets, full personal fields beyond badge number if policy forbids it.

Until that screen exists: screenshot FlashMessage + Charles status line, then file an incident.