Concept
How session tokens work
The key stays on your server. The browser holds a thirty-minute token that can only do what you allowed.
A server-side API key (header X-Api-Key, prefix ck_) is exchanged by your server for a thirty-minute browser session token (Authorization: Bearer), optionally bound to one system and one origin. The SDK sends the token on every request, refreshes it before expiry and never sees the key.
The API key
Created in the dashboard under Settings › API Keys. Each key has a name, a permission and a list of websites:
- Read & write (
ck_): the full key. The configurator can save and share projects and upload renders. Use it in your own tools and on your server to request session tokens. - Read only (
ck_ro_): browse, configure and price; nothing is ever written. It can only requestcatalogtokens. - Websites: at least one is required.
shop.example.comfor a site,*.example.comfor its subdomains,localhost:5173with the port for a developer's machine. The browser is refused before the key is even checked on any host not listed.
A key is shown in full once, when created, then masked. Its permission and its websites can be changed at any time; Revoke stops it for good, and every token made from it within about thirty seconds.
The token route
One route on your server. The key stays in an environment variable here and nowhere else; the response goes back to the page as-is.
// server.js
app.post('/configurator-token', async (req, res) => {
const r = await fetch('https://api-configurator.imagine.io/api/v1/auth/token/', {
method: 'POST',
headers: { 'X-Api-Key': process.env.CONFIGURATOR_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ scope: 'session', system_id: 12, origin: 'https://www.your-site.com' }),
});
res.status(r.status).json(await r.json()); // { access_token, expires_at, ... }
});The three body fields are optional. Each narrows what the token can do, and narrower is safer:
scope | session can save projects and upload renders; catalog can only load, configure and price. |
system_id | Lock the token to the one system this page shows. |
origin | Lock the token to your site, so one lifted from the page is useless anywhere else. It must be the page's exact origin (scheme, host, port) and must be in the key's websites list; a token minted for an origin the key does not allow is refused at mint time, and a page on another origin is refused on every request with ORIGIN_NOT_ALLOWED. |
The page
const app = mount('#root', {
systemId: 12,
getToken: async () => (await fetch('/configurator-token', { method: 'POST' })).json(),
});The SDK calls getToken at boot, again shortly before the token expires, and once more on a 401. No VITE_API_KEY exists in a production build. For local development only, the key can sit in .env.local as VITE_API_KEY and the SDK reads it directly.
The flow
Browser (SDK) ──► your server ──► imagine.io POST /api/v1/auth/token/ (X-Api-Key)
◄── token ◄── imagine.io creates it and answers { access_token, expires_at, ... }
Browser (SDK) ──► imagine.io every request: Authorization: Bearer <token>Related
Frequently asked questions
Why not put the API key in the page?
The key is long-lived and reads your whole catalog; anyone who views the page source would have it. A session token lives thirty minutes, can be locked to one system and one origin, and can only do what its scope allows, so one lifted from a page is nearly useless.
What does the SDK do when the token expires?
It calls your token route again shortly before the token expires, and once more if a request answers 401. There is nothing to refresh by hand.
What is the difference between session and catalog scope?
session can save projects and upload renders; catalog can only load, configure and price. A read-only API key (ck_ro_) can only mint catalog tokens.
I revoked a key. How fast do its tokens stop?
Within about thirty seconds. Every token minted from that key stops working; pages fall back to your token route, which now fails, and the configurator shows the refusal.
Why does the key work on localhost but not on the site?
Because the site's host is not in the key's websites list. Add it under Settings › API Keys as shop.example.com or *.example.com. An entry must match the port as well, which is why development needs localhost:5173 rather than localhost.
Troubleshooting
Every request is refused with ORIGIN_NOT_ALLOWED, and the browser calls it a CORS error.
The page's origin is not in the key's websites list, or the token was minted with a different origin from the page's. The backend answers 403 without CORS headers, so the browser reports CORS; the body in the Network tab names the origin it saw. Add that exact origin under Settings › API Keys, with the port for localhost, and mint the token with the same value. A server-to-server call sends no Origin and is not subject to this check.