Local Development with localhost

Production origins must use https, but UPCS allows http://localhost:5173 as an origin so you can build and test on your own machine. The origin must still be registered and must match exactly, including the port.

Setup

1. In the partner panel, add http://localhost:5173 (or whichever port your dev server uses) to Allowed origins for your key.
2. Put the key in a local environment file that is ignored by version control, for example UPCS_API_KEY=upcs_....
3. Run a small local backend that creates sessions. Your dev front end calls it; the backend calls UPCS.
4. Send the same origin string, http://localhost:5173, in the session request.

curl -X POST https://api.upcs.io/api/v1/embed/sessions \
  -H "x-api-key: $UPCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"http://localhost:5173"}'

Dev server proxies

Frameworks such as Vite let you proxy /upcs-session to a local backend, which avoids cross-origin issues between your dev server and API:

// vite.config.js (illustrative)
export default {
  server: {
    port: 5173,
    proxy: { '/upcs-session': 'http://localhost:3000' }
  }
};

Common problems

• origin_not_allowed: the port differs from the registered one, or you opened the site at 127.0.0.1 instead of localhost. These are different origins.
• Works locally, fails in staging: the staging origin was never added; see allowed origins explained.
• Key committed by accident: rotate it using API key rotation.

Test without spending your limit

Keep the number of session requests low while developing by reusing a session until it expires; see embed session TTL and renewal and testing a location integration. Remove the localhost origin from production keys when you finish.