> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Call a hosted Forge API from a frontend on Vercel, Netlify or your own host

> Keep your frontend where it is and call a Forge API on Reliant hosting, with sign-in that works: a same-site API hostname, credentialed CORS, and the frontend declared as the sign-in origin.

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](https://docs.reliantlabs.io/guides/forge/deploy-static-site-cdn.md)).

## 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](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) 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:

```bash terminal theme={null}
reliant forge domain add api.example.com --env prod
reliant forge domain bind api.example.com --env prod --target api
```

Publish the CNAME and TXT records `domain add` prints. HTTPS is issued once they verify. [Add a custom domain with automatic HTTPS](https://docs.reliantlabs.io/guides/hosting/custom-domain-https.md) 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`:

```python deploy/kcl/prod/main.k theme={null}
_workloads = [
    _hosted(wl.migrate)
    _hosted(_api | {env = {CORS_ORIGINS = "https://app.example.com", CORS_ALLOW_CREDENTIALS = "true"}})
]
```

`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:

```bash terminal theme={null}
reliant forge env render prod 2>&1 | grep -o '"name":"CORS_[A-Z_]*","value":"[^"]*"'
```

```text Output theme={null}
"name":"CORS_ALLOW_CREDENTIALS","value":"false"
"name":"CORS_ORIGINS","value":"https://app.example.com"
"name":"CORS_ALLOW_CREDENTIALS","value":"true"
```

The first line is the `migrate` job, which serves no browser. The other two are the API.

> [!NOTE]
>
> 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:

```python deploy/kcl/identity.k theme={null}
# The origin of the frontend you host elsewhere, per env that has one.
_frontends = {
    prod = "https://app.example.com"
    staging = "https://staging-app.example.com"
}
_frontend = _frontends[option("env")] if option("env") in _frontends else ""

IDENTITY = forge.ManagedIdentity {
    roles = [...]
    methods = ["password", "passkey"]
    if _frontend:
        applications = [forge.IdentityApplication {
            name = option("env") + ":api"
            workload = "api"
            login_uri = _frontend + "/auth/sign-in"           # the frontend's sign-in page
            redirect_uris = [_frontend + "/auth/callback"]
        }]
}
```

An environment without an entry, such as `dev`, keeps its derived application. Check what each environment declares:

```bash terminal theme={null}
reliant forge env shape prod --json | jq '.shape.identity.applications[] | {name, login_uri, redirect_uris}'
```

```text Output theme={null}
{
  "name": "prod:api",
  "login_uri": "https://app.example.com/auth/sign-in",
  "redirect_uris": [
    "https://app.example.com/auth/callback"
  ]
}
```

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

```bash terminal theme={null}
reliant forge env deploy prod
reliant forge obs check prod --wait --json
```

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:

```ts src/lib/connect.ts theme={null}
import { createConnectTransport } from "@connectrpc/connect-web";

export const transport = createConnectTransport({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!, // https://api.example.com
  fetch: (input, init) => fetch(input, { ...init, credentials: "include" }),
});
```

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

> [accordion] 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).

> [accordion] 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.

> [accordion] 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

> [card] [Add sign-in with passkeys](https://docs.reliantlabs.io/guides/forge/add-sign-in-passkeys.md)
>
> Turn on passkeys and magic links, and choose what stays public.

> [card] [Add a custom domain](https://docs.reliantlabs.io/guides/hosting/custom-domain-https.md)
>
> Claim, verify and bind the API's hostname.

> [card] [The config system](https://docs.reliantlabs.io/forge/concepts/config-system.md)
>
> Every setting the API reads, including the CORS fields.

> [card] [Middleware and the request path](https://docs.reliantlabs.io/forge/concepts/middleware-and-request-path.md)
>
> Where CORS sits in front of every request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.