Integration guide
Your API key is a server-side secret: it must only be used from your backend,
never from browser JavaScript or a mobile app. The pattern is always: your backend calls
the API, gets a short-lived URL, and redirects the user's browser to it.
{/* Reference tab */}
{tab === 'reference' && (
{sectionHead('Endpoint')}
POST
{BASE}/v1/enroll/session
{sectionHead('Authentication')}
Pass your API key in the Authorization header:
Authorization: Bearer sk_live_…
{sectionHead('Request body')}
There are two ways to identify the customer: use whichever fits how
your login works. Both need programId and consentGiven: true.
Option A: you already have a Spoonity session key
If your customer's login already goes through Spoonity, pass their session_key and
we'll fetch their real name/email/id directly from Spoonity, you don't provide them yourself.
Option B: you have your own user data
If you maintain your own customer accounts (not tied to a live Spoonity session), pass their
details directly.
{sectionHead('Response')}
Redirect the user's browser to sessionUrl. The link is single-use and expires in
15 minutes. If alreadyEnrolled is true, the user already has a pass;
the sessionUrl will still take them to it.
{sectionHead('Error codes')}
{ERRORS.map(([code, desc], i) => (
{code}
{desc}
))}
{sectionHead('Security notes')}
{[
'Never put your API key in browser JavaScript, a mobile app, or version control.',
'Building a mobile app with no backend of its own? Don\'t try to embed a key - use the Mobile Apps tab instead, which needs no server secret at all.',
'Store it as an environment variable (e.g. SPOONITY_API_KEY) and read it at runtime.',
'Each key is scoped to one program: it cannot access other programs\' data.',
'Revoke a key immediately if it\'s ever accidentally exposed.',
].map((note, i, arr) => (
·
{note}
))}
{sectionHead('Other endpoints')}
Same API key, same Authorization: Bearer sk_live_… header as above.
POST
{BASE}/v1/members/favorite-store
Refreshes an existing member's favorite store (used to personalize their pass's
location features). Not part of enrollment: call it any time after the fact, whenever you have
the Spoonity user_id for a customer who already has a pass in this program.
Request body
Response
updated: false with a null favoriteLocation isn't an error: it just means Spoonity
has no ranked favorite for that customer yet (e.g. no transaction history). Their previously
recorded favorite, if any, is left untouched rather than cleared.
Error codes
{FAVORITE_STORE_ERRORS.map(([code, desc], i) => (
{code}
{desc}
))}
)}
{tab === 'appSession' && (
For a vendor's own native or mobile app with no backend of its own to hold a
server secret. This is a different endpoint from the rest of this guide: it needs
no API key at all. Instead, the customer's own live Spoonity session key
(from your app's existing Spoonity login) proves who they are; it only resolves against
this program's own vendor, so it can't be used to enroll anyone else.
Use this only when there's no backend in the picture. If your app talks to your
own server first, use the server-side flow instead (API Reference tab). It's the same idea,
just called from a place that can actually keep a secret.
{sectionHead('Endpoint')}
POST
{BASE}/enroll/app-session
{sectionHead('Authentication')}
None: no header, no key. The spoonitySessionKey in the request body is
the authentication.
{sectionHead('Request body')}
{sectionHead('Response')}
Same shape as the server-side flow: open sessionUrl in an in-app browser / system
webview. It's single-use and expires in 15 minutes.
{sectionHead('Example (JavaScript / React Native)')}
The same request works from any platform (Swift, Kotlin, etc.). It's just a plain POST with
a JSON body, no auth header to construct.
{sectionHead('Error codes')}
{APP_SESSION_ERRORS.map(([code, desc], i) => (
{code}
{desc}
))}
{sectionHead('Security notes')}
{[
'There\'s no key to leak here, but the spoonitySessionKey is still the customer\'s own live session - treat it the same way you\'d treat any auth token (don\'t log it, don\'t send it anywhere except this endpoint).',
'consentGiven must reflect a real, explicit action by the customer in your app (e.g. tapping "Add to Wallet") - not a default or a pre-checked box.',
'This endpoint can only enroll the customer who owns the session key it\'s given; it cannot be used to enroll or look up anyone else.',
].map((note, i, arr) => (
·
{note}
))}
)}
{tab === 'nodejs' && (
Works with Express, Next.js API routes, Fastify, or any Node.js server.
Requires Node 18+ (built-in fetch) or install node-fetch.
Or, if you already have a Spoonity session key
)}
{tab === 'python' && (
Works with Flask, Django, FastAPI, or any Python backend.
Install the requests library: pip install requests
Or, if you already have a Spoonity session key
)}
{tab === 'php' && (
Works with Laravel, WordPress, Symfony, or plain PHP.
Uses the built-in curl extension (enabled by default on most hosts).
Or, if you already have a Spoonity session key
)}
{tab === 'curl' && (
Useful for testing the API from your terminal before writing code.
Replace sk_live_YOUR_API_KEY with your actual key.
Or, if you already have a Spoonity session key
)}
);
}
/* Full-screen integrations view mounted by SpoonityApp when view === "integrations". */
function IntegrationsView({ onHome, accent = '#cc6716' }) {
const [programs, setPrograms] = React.useState(null); // null = loading
const [selectedProgram, setSelectedProgram] = React.useState('');
const [keys, setKeys] = React.useState(null);
const [keysLoading, setKeysLoading] = React.useState(false);
const [creating, setCreating] = React.useState(false);
const [newKeyData, setNewKeyData] = React.useState(null);
const [showRevoked, setShowRevoked] = React.useState(false);
const [error, setError] = React.useState('');
const [section, setSection] = React.useState('keys'); // 'keys' | one of DOC_TABS' ids
const mainRef = React.useRef(null);
// The content pane is one persistent scrollable element across every tab (only its children
// swap), so its scrollTop otherwise carries over from whichever tab you were previously on.
React.useEffect(() => { if (mainRef.current) mainRef.current.scrollTop = 0; }, [section]);
const navStyle = (id) => ({
padding: '9px 12px', border: 'none', borderRadius: 8, textAlign: 'left', width: '100%',
background: section === id ? accent : 'transparent',
color: section === id ? '#fff' : 'var(--typography-secondary)',
fontFamily: 'var(--font-sans)', fontSize: 13, fontWeight: 600,
cursor: 'pointer', transition: 'background .15s, color .15s',
});
const navGroupLabel = (text) => (