Authenticate Requests
This page sets up authentication for your front end in every environment it runs in. You confirm the default posture when the C3 Agentic AI Platform serves the application, understand why local development reaches no backend session, and choose and apply the transport for your production topology. When you finish, you understand how the served application authenticates and you have selected the correct transport for where it runs in production.
Authentication on C3 is not a choice between cookies and tokens. Identity is delegated to the cluster identity provider (IdP), and after login the C3 Agentic AI Platform issues one signed session token that can travel several ways. The steps decide which transport carries that token for your deployment.
For most developers building an application served by the C3 Agentic AI Platform, authentication is automatic and requires no code. Read past Step 1 only if your application runs on a separate server.
Before you begin
Have the application making API calls, from Make API Requests, and know where the front end runs in production: served by the C3 Agentic AI Platform, or hosted off the C3 Agentic AI Platform.
Step 1: Confirm the default when C3 serves the application
Confirm that a C3-served application needs no authentication code. When the C3 Agentic AI Platform serves the application, the session token sits in an HttpOnly cookie named c3auth that the browser sends automatically on every same-origin request, paired with a c3csrf cookie that defeats cross-site request forgery. Because the cookie is HttpOnly, no token reaches JavaScript, which makes this the default and the most secure posture.
End state: you have confirmed that no authentication code is required for the served application.
Step 2: Expect no authenticated session in local development
Expect no authenticated backend session when you run npm run dev, because by default the dev server serves only the interface and reaches no environment. On your machine an api/8/... call resolves to localhost, where no C3 backend answers, so it returns 404 rather than data. The default scaffold configures no dev proxy or local session token. Build the interface against the shape your data client returns, and confirm the data path after you deploy, which The Local Dev Loop covers, along with the optional proxy that reaches a running environment during development.
Authentication happens only once the C3 Agentic AI Platform serves the application, where the same-origin c3auth cookie authenticates each call automatically with no code. You reach that served state by deploying to a single-node environment with the C3 AI extension's Start Application, or to a shared environment through C3 Studio.
End state: you understand that local calls reach no backend, and that the served application authenticates through the cookie.
Step 3: Choose the transport for your topology
Choose the production transport from where the front end runs, not from preference:
- Served by C3. Use the same-origin
c3authcookie, which is the default and needs no code. - Hosted off the C3 Agentic AI Platform. Use a session token in an
Authorizationheader, because the cookie does not apply cross-origin. Keep the token in memory rather than storage, and keep it short-lived. - Off-platform, needing cookie-level safety. Put a backend-for-frontend (BFF) server in front, holding the token server-side and exposing a same-origin cookie to the browser.
End state: you have selected the transport that matches your deployment.
Step 4: Apply a cross-origin transport if needed
If the front end runs off the C3 Agentic AI Platform, present the token in an Authorization header rather than relying on the cookie. The same token authenticates through a C3Bearer header, through Basic with an empty username and the token as the password, or through an ?auth= query parameter:
const base = { method: 'POST', credentials: 'omit' as const, headers: { 'Content-Type': 'application/json' } }
await fetch(url, { ...base, body, headers: { ...base.headers, Authorization: `C3Bearer ${token}` } }) // 200To use the cookie cross-origin instead, request that an administrator add your origin to the Cross-Origin Resource Sharing (CORS) allowlist, because the default posture allows a token header cross-origin but not the cookie.
End state: cross-origin calls authenticate with a token header, or the origin is allowlisted for cookies.
What you have now
Your application authenticates through the c3auth cookie once the C3 Agentic AI Platform serves it, and you have chosen and applied the production transport for its topology. The reference sections that follow cover the full set of transports and the CORS boundary.
Reference: the transports
The same signed token authenticates through several transports, and a call with no credential returns 401. Each of the following returns 200:
// 401 no credential
await fetch(url, base)
// 200 header
await fetch(url, { ...base, body, headers: { ...base.headers, Authorization: `C3Bearer ${token}` } })
// 200 Basic, empty user with token as password
await fetch(url, { ...base, body, headers: { ...base.headers, Authorization: `Basic ${btoa(':' + token)}` } })
// 200 query parameter
await fetch(`${url}?auth=${token}`, { ...base, body })Reach for the header when a client speaks in headers, and treat the query parameter as a last resort, because the token then lands in server logs and browser history.
Reference: the CORS boundary
CORS sets the limit on cross-origin calls. The default posture returns Access-Control-Allow-Origin: *, which lets a different-origin browser call the backend with a token header but not with the cookie, because browsers refuse to send credentials to a wildcard origin. Enabling cookie authentication cross-origin requires an administrator to add the origin to an allowlist, at which point the C3 Agentic AI Platform echoes that specific origin and permits credentials. Identity itself is always delegated to the cluster IdP over OpenID Connect (OIDC) or Security Assertion Markup Language (SAML); the cookie or token is only the session artifact issued after that login.
Decisions on this page
The transport and the cross-origin posture follow from the deployment.
| Decision | Options | Recommendation |
|---|---|---|
| Transport | the same-origin c3auth cookie, a token header, or the ?auth= query | The cookie when C3 serves the application; a token header cross-origin or for a non-browser client |
| Topology | C3-served, off-platform, or a backend-for-frontend | Match the transport to where the front end runs |
| Cross-origin cookies | wildcard CORS, which allows a token only, or an allowlist with credentials, which an administrator gates | Wildcard by default; the allowlist only when cookie authentication must work cross-origin |