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.

, imagine.io ·

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.

Browserthe SDK on your pageasks your server for a token,keeps it; never sees the keyYour serverholds the API key,asks imagine.io for a token,passes the token to the pageimagine.iochecks the key and origin,issues a thirty-minute token,checks it on every call1asks for a token2asks with the key3token, 30 min4token to the page5every request: Authorization: Bearer <token>refreshed before expiry and once on a 401; revoke the key and every token stops within ~30 sthe key never leaves your server; the token can be locked to one system and one origin Browserthe SDK on your pageasks your server for a token,keeps it; never sees the keyYour serverholds the API key,asks imagine.io for a token,passes the token to the pageimagine.iochecks the key and origin,issues a thirty-minute token,checks it on every call1asks for a token4token to the page2asks with the key3token, 30 min5every request: Bearer <token>refreshed before expiry and once on a 401;revoke the key and every token stops within ~30 sthe key never leaves your server;the token can be locked toone system and one origin
The API key stays on your server. The browser holds a thirty-minute token that can only do what the scope allows.

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 request catalog tokens.
  • Websites: at least one is required. shop.example.com for a site, *.example.com for its subdomains, localhost:5173 with 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:

scopesession can save projects and upload renders; catalog can only load, configure and price.
system_idLock the token to the one system this page shows.
originLock 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>

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.

SDK documentation · Admin guide