Authentication

Authentication

Agent4API separates access to its control plane from the upstream business-user identity used by imported APIs.

Identity boundaries

• The administrator cookie and CSRF token authorize administration.
• Agent API keys authorize compatible API clients.
• Browser Chat uses its own high-entropy browser subject cookie.
• Embedded Chat uses an anonymous bearer Embed Session bound to one Embed, Agent, and parent origin.
• Tool Sessions hold upstream API credentials and are bound to their creating owner and Agent.

Anonymous users can chat with a public Embed and call unprotected Tools. They cannot silently acquire credentials for protected upstream APIs.

Configure OAuth 2.0 on the API Source

Open API Sources, select OAuth 2.0, and configure:

• Authorization URL;
• Token URL;
• optional Device Authorization URL;
• Client ID and encrypted Client Secret;
• scopes;
• optional callback URL override;
• enabled state.

The administration page displays both callback values:

Recommended: {base_url}/api/tool-sessions/oauth/pkce/callback
Effective:   callback override, or the recommended address when no override exists

Register the effective address with the upstream OAuth provider. Leaving Client Secret blank during an edit keeps the existing encrypted secret.

Embedded authorization

When an Agent reaches a Tool whose API Source requires authorization, AG-UI emits authorization_required. The Widget displays a user action; it never opens a popup automatically.

For PKCE, the popup performs authorization at the upstream provider. For configured Swagger login, it collects credentials on the Agent4API origin and executes the login Tool once. CAPTCHA, MFA, consent, and other interactive challenges are not bypassed.

The result page sends only a short-lived one-time grant to its opener using an exact targetOrigin. It never places OAuth tokens, Tool Session tokens, passwords, or client secrets in a URL or postMessage payload. The iframe exchanges the grant, binds the resulting Tool Session to its Embed Session, and resumes the same conversation.

Grants are stored only as hashes, expire within five minutes and no later than the Embed Session, and are consumed atomically once. Replays, another Embed owner, another Agent, or another origin are rejected.

Revocation and expiry

The Widget can log out a source without ending the anonymous chat. Tool Session idle and absolute expiries are checked before upstream traffic. OAuth refresh may occur immediately before a Tool call and may replay once after an upstream 401; it never starts an interactive flow during Tool execution.

Disabling an Embed or Agent prevents new sessions. Revoking an Agent API key immediately invalidates the Tool Sessions it owns. Embed-owned Tool Sessions cannot be reused by an administrator, browser Chat subject, API key, different Agent, or different Embed Session.

For CLI Device Flow, PKCE administration, credential injection, and compatible API examples, see Tool Session Authentication.