/_api, so the session cookie is first-party and CORS is not involved (Deploy a static site).
Before you begin
- A Forge API project deployed to a hosted environment, here
prodserving a workload namedapi, with managed identity (the scaffoldeddeploy/kcl/identity.k). Deploy a Go API with managed Postgres gets you there. - A frontend already served from a hostname you control, here
https://app.example.com, and access to that domain’s DNS. - Forge v1.6.1 or later (
reliant forge --versioninside the project). This guide’s KCL was rendered with it.
Why the hostname matters
Forge’s sign-in sets an HttpOnly session cookie withSameSite=Lax. A browser sends such a cookie only to the same site, meaning the same registrable domain. app.example.com and api.example.com are the same site. my-app.vercel.app and the API’s platform hostname are not, and there sign-in appears to work but every call after it answers 401, because the cookie never comes back. If the frontend calls only public RPCs (auth_required: false) and never signs anyone in, skip step 1: any hostname works.
1
Give the API a hostname on the frontend's domain
Claim a subdomain of the frontend’s domain and bind it to the API workload:Publish the CNAME and TXT records
terminal
domain add prints. HTTPS is issued once they verify. Add a custom domain with automatic HTTPS covers each state.2
Allow the frontend's origin, with credentials
The API answers browsers on another origin only when The first line is the
CORS_ORIGINS names that origin, and lets them send the cookie only when CORS_ALLOW_CREDENTIALS is on. Set both on the API’s binding line in deploy/kcl/prod/main.k:deploy/kcl/prod/main.k
CORS_ORIGINS is the frontend’s exact origin, scheme included and no trailing slash. Separate several with commas. A wildcard origin with credentials is refused when the API loads its config, because browsers reject that combination.Check what the render gives the API:terminal
Output
migrate job, which serves no browser. The other two are the API.In a project that also hosts a Forge frontend, the shared
hosted binder in deploy/kcl/base/env.k sets the API’s CORS_ORIGINS to that frontend’s URL, and its value wins over the binding line above. That file is yours: edit the CORS_ORIGINS line there instead, listing both origins.3
Make the frontend the origin sign-in trusts
The sign-in routes refuse a POST from any origin except the API’s own and the app’s, and the app’s origin is the one in the sign-in URL the identity delivers to the API (An environment without an entry, such as Without managed identity, set
IDP_LOGIN_URI). With managed identity, Forge derives that from a frontend it hosts or the environment’s first bound domain. For a frontend it does not host, declare the application’s URIs in deploy/kcl/identity.k. Every environment imports this file, so pick the frontend per environment:deploy/kcl/identity.k
dev, keeps its derived application. Check what each environment declares:terminal
Output
IDP_LOGIN_URI on the API to the frontend’s sign-in URL instead. Skip this step and the browser’s sign-in POST answers 403, however CORS is set. A sibling such as https://evil.example.com is refused too: the check is the exact origin, not the site.4
Deploy the API
terminal
5
Call the API with credentials from the frontend
Point the frontend at A frontend Forge scaffolded already does this in
https://api.example.com through its own host’s environment settings, and send the cookie on every request with credentials: "include". The browser’s default, same-origin, silently drops the cookie on a cross-origin call. With Connect RPC:src/lib/connect.ts
src/lib/connect.ts, and its sign-in page (src/app/auth/sign-in/, with src/lib/auth/native-login.ts) posts to the API’s sign-in routes with credentials too. If your frontend was not scaffolded by Forge, those files are the working example to follow.What this does not do
- Preview deploys on the frontend’s host get their own origins. List each one you need in
CORS_ORIGINSand the identity’s URIs, or sign in only on the production origin. - A different registrable domain cannot sign in. No setting makes a
SameSite=Laxcookie cross sites. Use a subdomain of the frontend’s domain for the API. - Forge does not deploy or watch the frontend. It builds, releases and checks the API only; the frontend’s host keeps deploying the frontend.
Troubleshooting
Sign-in answers 200, then every call answers 401
Sign-in answers 200, then every call answers 401
The browser is not sending the session cookie. Either the API is on another site than the frontend (step 1), or the frontend’s requests lack
credentials: "include" (step 5).The browser's sign-in POST answers 403
The browser's sign-in POST answers 403
The API does not trust the frontend’s origin for sign-in. Declare the frontend’s URIs in
identity.k (step 3), deploy, and check env shape shows them.The browser reports a CORS error
The browser reports a CORS error
CORS_ORIGINS does not match the page’s origin exactly (scheme, host and port, no trailing slash), or CORS_ALLOW_CREDENTIALS is off. Run the render check in step 2.Next steps
Add sign-in with passkeys
Turn on passkeys and magic links, and choose what stays public.
Add a custom domain
Claim, verify and bind the API’s hostname.
The config system
Every setting the API reads, including the CORS fields.
Middleware and the request path
Where CORS sits in front of every request.