Square credentials and OAuth redirects
Application name in the Square Developer Console: FoodTruckNerdz (renamed from ftn-site-vercel).
Selected use cases (2026-08-08)
- Enabled
-
-
Accept payments (online, in-app, in-person)
-
Build customer relationships (customers, loyalty, gift cards)
-
Manage a team
-
Manage a product catalog
-
- Not enabled (yet)
-
-
Manage and fulfill orders
-
Adjust inventory
-
API version for the app was upgraded to the latest (from mid-last-year). Prefer webhook subscriptions for realtime Square events when we wire them.
There is no Square “developer CLI” for redirects
Square does not ship a winget/npm CLI that updates OAuth redirect URLs. Registration is via the Developer Console → application → Sandbox or Production toggle → OAuth → Redirect URL(s).
Register both callback paths our app uses (POS link + Better Auth), for each environment that needs them:
| Environment | Redirect URIs |
|---|---|
Sandbox / local |
|
Production (current web host) |
|
Env vars: SQUARE_APP_ID, SQUARE_APP_SECRET, SQUARE_REDIRECT_URI (POS path), SQUARE_ENVIRONMENT=sandbox|production. Better Auth uses the oauth2 callback path relative to BETTER_AUTH_URL.
What each token is for
| Credential | Role |
|---|---|
Application ID ( |
Public client id for OAuth authorize URLs (sandbox ids often look like |
Application secret ( |
Private OAuth client secret used only on the server when exchanging an authorization |
Sandbox Access Token (Developer Console → Credentials / OAuth) |
A convenience token for your sandbox application / default sandbox seller context — useful for quick API calls without running a full OAuth dance. Not a substitute for the application secret. |
Default Test Account Access Token |
Token for a specific make-believe seller (Sandbox test account). Use when you need that seller’s catalog/locations/payments. Different from the app-level sandbox access token because each test account is its own merchant. |
Production Application ID / Secret |
Same roles as sandbox, but for live sellers. Keep separate fields in Bitwarden. |
Seller OAuth access + refresh tokens (stored encrypted in Convex after connect) |
Per-seller tokens obtained when a real (or sandbox) merchant authorizes FoodTruckNerdz. These are what production POS sync uses — not the dashboard “Sandbox Access Token”. |
Rule of thumb: secret = prove our app’s identity during OAuth; access token = call Square APIs as some merchant (app default, test account, or connected seller).
Pre-order / QR idea (product note)
Charging online (platform or seller) then presenting a QR for the seller to confirm fulfillment is feasible with Square Payments + Orders, but needs a clear money path:
-
Seller-of-record (recommended for food): OAuth the truck’s Square account; charge on their behalf; FTN takes an application fee / separate fee — Square supports additional recipients / app fees depending on product.
-
FTN-of-record: we charge, then settle to sellers — heavier compliance (money transmission / marketplace) and not “just a few cents” without legal review.
Proximity pay / seller-shown QR remains the common walk-up path; pre-order is the differentiator for parties and delivery planning.