Authentication

A hosted agent has two access decisions: whether a visitor can open the app, and whether a request can use the runtime.

Set these fields in Settings > Auth or with PUT /api/agents/{agent_id}, which requires an admin automation token. They belong to the platform agent record, not amodal.json. Redeploy after changing the runtime identity configuration.

Hosted browser login

For a team-only app served at the agent's own origin, including a custom React app:

1. Open the agent URL. The edge redirects an unauthenticated visitor to /auth/login.
2. Sign in through the hosted login flow. The edge checks organization membership and sets an HttpOnly amodal_session cookie.
3. Make same-origin runtime calls. The edge validates the cookie and adds the bearer header before forwarding the request.

Use window.location.origin as the SDK URL and omit getToken for this flow:

import { AmodalProvider, AmodalChat } from '@amodalai/react';
import '@amodalai/react/style.css';
 
<AmodalProvider runtimeUrl={window.location.origin}>
  <AmodalChat />
</AmodalProvider>;

The browser cannot read the HttpOnly cookie. /auth/session returns user identity, not a bearer token. Login requires a full-page navigation; an API fetch cannot complete the hosted login redirect.

API clients

CLI tools, CI jobs, and application servers send Authorization: Bearer <credential>:

The edge accepts agent-bound platform runtime tokens and ak_ keys on team-only agents. You can run API smoke tests without opening the app to the public.

Keep persistent credentials out of browser code. A public app that offers chat needs a backend to authorize runtime access; setting public does not issue anonymous chat tokens.

Embedding in another product

For a multi-tenant product, proxy runtime calls through your backend and keep runtime credentials there. See Embedding & Multi-tenancy for the required checks.

When you use both AmodalProvider and AmodalChat, pass getToken to each. AmodalChat inherits only the provider's URL.

Identity settings

The Auth page stores one end-user identity configuration in end_user_auth:

The OIDC form also shows client secret, callback URL, scopes, session secret, cookie, and TTL fields. They are stored but not used.

Hosted chat

The hosted chat runtime installs the jwks verifier when the client ID, issuer, JWKS URL, and audience are all known. The audience defaults to the client ID. The verifier checks issuer and audience, then checks agent membership. It replaces the platform JWT verifier for that runtime, so platform runtime tokens stop working there; ak_ keys still work.

With any other type, hosted chat uses the platform JWT verifier. Saving jwt_secret, oidc, header, or custom does not change how hosted chat authenticates.

On a team-only origin, the edge still requires its hosted session, an ak_ key, or an agent-bound platform runtime token. An external JWT does not bypass that gate.

Platform API

The Platform API accepts an end-user JWT only when the token has a sub claim and either an agent_id claim naming the agent or, for oidc, an iss matching the configured issuer. The sub becomes the end-user ID. An end-user JWT can reach only session and per-scope secret routes. Session routes return only sessions the user owns, and secret routes require the scope to equal its sub.

header does not authenticate a request. On a request already authenticated for the agent, the Platform API reads the end-user ID from the configured header, or X-End-User-Id when the name is blank. Use it only behind a proxy that strips client-supplied copies of that header.