Skip to main content
By the end of this guide, a frontend you host yourself (on Vercel, Netlify or any other host) signs users in through a Forge API on Reliant hosting and calls it with their session. Forge does not build or serve that frontend, so the values it would otherwise wire for you are written out by hand: the API’s hostname, the origins it trusts, and where sign-in starts. A frontend that Forge does host needs none of this. It calls the API on its own origin, at /_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 prod serving a workload named api, with managed identity (the scaffolded deploy/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 --version inside the project). This guide’s KCL was rendered with it.

Why the hostname matters

Forge’s sign-in sets an HttpOnly session cookie with SameSite=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:
terminal
Publish the CNAME and TXT records 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 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
The first line is the 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 (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
An environment without an entry, such as dev, keeps its derived application. Check what each environment declares:
terminal
Output
Without managed identity, set 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
The CORS settings and the identity application ship with the release like any other declaration.
5

Call the API with credentials from the frontend

Point the frontend at 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
A frontend Forge scaffolded already does this in 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_ORIGINS and the identity’s URIs, or sign in only on the production origin.
  • A different registrable domain cannot sign in. No setting makes a SameSite=Lax cookie 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

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 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.
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.