Guides Overview
What each guide is for, the recommended methodology, and which guide to hand to which application.
The guides, explained
Client App Guide
Client-facing apps · own data backend
For customer-facing products that keep their OWN data backend untouched. They register Cargo as a Custom OIDC Provider with Auto-discovery OFF (manual endpoints; issuer copied from live discovery — the backend host) — NOT Third-Party Auth — disable local login, and use one signInWithOAuth('custom:cargo-ac') button. The backend mints its own native session, auto-provisions users (JIT), and verifies the app_access claim for entitlement.
Covers: CargoWorks AI (exim.cargoworks.ai), CargoWorks IO (track.cargoworks.io), Cargo Directory (global.cargo.directory). Cargo E-Mail follows the same pattern.
CargoApp Guide (Flutter native)
Native mobile app · own data backend
The dedicated native-mobile playbook for CargoApp (mob.cargo.app). Same Model 2 federation, but with mobile mechanics: supabase_flutter signInWithOAuth(OAuthProvider('custom:cargo-ac')) opens the system browser, the user returns via a deep link, and the app ships NO client secret (PKCE public client to its own backend api.cargo.app, which stays a confidential relying party server-side). For mobile the key insight is that one.cargo.ac stays a normal web app rendered inside the phone's in-app browser — only the final redirect is a deep link. Includes iOS/Android deep-link setup.
Covers: CargoApp (mob.cargo.app). Hand the MASTER Federation Doc (One Login Kit) to Cursor — it also contains the one.cargo.ac and hub sections so all three teams share one document.
Internal App Guide
Internal tools · own data backend
Same Model 2 flow for internal staff tools: register the Custom OIDC Provider with Auto-discovery OFF (manual endpoints; issuer copied from live discovery), one signInWithOAuth('custom:cargo-ac') button, native session minted locally, automatic JIT provisioning and global logout. Roles arrive from cargo.ac token claims, managed in admin.cargo.ac.
Hand to: internal tool teams (Network HUB, Exchange, ID, Expert, Support, Delivery, Cloud).
One Login Kit
Distributable package
The branded, print-ready PDF plus a paste-ready Markdown brief you drop straight into a spoke's platform chat. It tells that project's AI exactly what to remove, add and verify — disable local auth, add the Custom OIDC Provider with Auto-discovery OFF (issuer copied from live discovery), wire the single button, and verify provisioning + the app_access entitlement check — guidance to distribute, not a page to follow on-screen.
Hand to: any spoke about to migrate — give them the kit to self-serve.
one.cargo.ac Guide
Cargo Account · the account home
The account home — the ONLY place credentials live. It has real login, signup and reset screens, validates each incoming return URL, and bounces every user straight back to the spoke they came from, signed in. It SHARES this hub's backend, so no separate data project or OIDC provider.
Hand to: the one.cargo.ac team only.
Best methodology — what to share with what
signInWithOAuth('custom:cargo-ac') → the user authenticates on Cargo → the spoke's backend finishes the exchange at {dataBackend}/auth/v1/callback, auto-provisions the user (JIT) and mints its OWN native session. No shared JWT secret; entitlement is enforced by Cargo and re-checked via the app_access claim.- Owns its own data backend? → send the Client or Internal guide (federate via Custom OIDC Provider). For a hands-off handoff, give them the One Login Kit to paste into their own platform chat.
- Shares this hub's backend (only one.cargo.ac)? → send the one.cargo.ac Guide. Never the client/internal template — there is no separate data project, so no OIDC provider to register.
- Every guide is print-ready — open it and use Print / Save as PDF. The printed header shows each covered app's logo so you know which PDF is which.
Per-application directory
Cargo Account (shared backend)
| Application | Origin | Guide to use | OIDC status |
|---|---|---|---|
 one.cargo.ac (Cargo Account) | https://one.cargo.ac | Special | Pending |
Internal Tools
| Application | Origin | Guide to use | OIDC status |
|---|---|---|---|
 CW Network HUB | https://cargoworks.network | Internal | Pending |
 Exchange | https://exchange.cargoworks.network | Internal | Pending |
 CargoWorks ID | https://id.cargoworks.network | Internal | Pending |
 Expert | https://expert.cargoworks.network | Internal | Pending |
 Support | https://cargoworks.support | Internal | Pending |
 Delivery | https://delivery.cargoworks.network | Internal | Pending |
 Cloud | https://cloud.cargoworks.network | Internal | Pending |
Client Apps
| Application | Origin | Guide to use | OIDC status |
|---|---|---|---|
 CargoWorks AI | https://exim.cargoworks.ai | Client | Onboarded |
 CargoWorks IO | https://track.cargoworks.io | Client | Pending |
 Cargo Directory | https://global.cargo.directory | Client | Pending |
 Cargo E-Mail | https://cargo.email | Client | Pending |
 Cargo Page | https://vault.cargo.page | Client | Onboarded |
 CargoApp | https://mob.cargo.app | Mobile | Pending |
Websites
| Application | Origin | Guide to use | OIDC status |
|---|---|---|---|
| CW AI Website | https://cargoworks.ai | Client | Pending |
| CW IO Website | https://cargoworks.io | Client | Pending |
| Directory Website | https://cargodirectory.io | Client | Pending |