Authentication

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

Setting	What it controls
`hosted_auth_mode: "user_auth"`	Team-only app access. Visitors sign in as members of the agent's organization. This is the default.
`hosted_auth_mode: "public"`	Anyone can open the app. Chat, sessions, and stores still require runtime authentication.
`end_user_auth`	End-user identity configuration. Hosted runtime support depends on the selected mode; see Identity settings.

Set these fields in Settings > Auth or with PUT /api/agents/{agent_id}. 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:

Open the agent URL. The edge redirects an unauthenticated visitor to /auth/login.
Sign in through the hosted login flow. The edge checks organization membership and sets an HttpOnly amodal_session cookie.
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>:

Credential	Purpose	How to create it
Short-lived runtime token	Expiring, agent-bound access for runtime calls. Can include `scope_id` and `context` claims.	Call `POST /api/agents/{agent_id}/tokens` from your server, for example with an operator/admin `pk_` token.
`ak_` agent API key	Persistent access for a service calling the runtime.	Create a key in the agent's API Keys settings. Keep it on your server.
`pk_` automation token	Platform operations such as configuring and deploying agents.	Create an organization automation token. Exchange it for a runtime token before calling chat.

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. Authenticate every request and authorize its scope, session, and operation. Keep runtime credentials there, including short-lived tokens with scope_id claims. Token scope does not restrict session history or validate resumed session IDs. See Embedding for the required checks.

Point the SDK at that proxy and return your application token from getToken. Pass the callback to both AmodalProvider and AmodalChat when you use both; the chat component inherits only the provider's URL.

Direct runtime calls, including hosted team login, are suitable for callers trusted to access the agent's sessions across scopes.

Identity settings

The Auth page exposes these configuration types:

Mode	Configuration purpose
`none`	No separate end-user identity provider. Hosted requests still use platform runtime credentials or agent API keys.
`jwks`	Verify end-user JWTs using a JWKS URL, issuer, and audience. Hosted deployments require a client ID and complete verifier settings.
`jwt_secret`	Verify HMAC-signed end-user JWTs on surfaces that support the shared-secret strategy.
`oidc`	Configure an external OpenID Connect provider.
`header`	Read identity from a trusted upstream proxy on surfaces that support header auth.
`custom`	Load an `AuthStrategy` module in a runtime host that uses the custom strategy.

The hosted chat runtime loads the configured jwks verifier when complete; otherwise it uses the platform JWT verifier. Saving jwt_secret, oidc, header, or custom settings does not install those strategies on hosted chat routes. The Platform API and a custom runtime host have different strategy support.

A configured hosted JWKS verifier checks the token's issuer and audience, then checks agent membership. It replaces the platform JWT verifier for that runtime. Platform runtime tokens are therefore not interchangeable with the IdP's tokens in this mode; ak_ access remains separate.

On a team-only origin, the edge still requires its hosted session, an ak_ key, or an agent-bound platform runtime token. An arbitrary external JWT does not bypass that gate. Verify both app access and chat authentication when configuring federation.

See Amodal Configuration for the fields shown in the Auth page.