Tool Session Authentication

Tool Session Authentication

Tool Sessions carry an upstream business user's identity separately from Agent4API access. An Agent API key authenticates a compatible client, while an administrator cookie authenticates browser administration. Neither credential is injected into imported APIs.

Each Tool Session is bound to one Agent, exactly one owner (the creating Agent key or administrator session), and one or more API sources. Cross-Agent, cross-key, cross-administrator-session, and cross-source reuse is rejected. States are authorization_required, pending, ready, expired, revoked, and failed.

Before choosing a mode

Import and enable the API source and required Tools. For OAuth, configure the source through PUT /api/admin/sources/{source_id}/oauth; endpoint URLs and client material are encrypted at rest.

For injected credentials, requested Header or Cookie names must be declared by the source's OpenAPI security schemes or the legacy-compatible allow-list extension.

Administrator writes require the administrator cookie and X-CSRF-Token. CLI or headless calls use Authorization: Bearer <Agent API Key>.

OAuth Device Authorization Grant

Use Device Flow for CLI or headless clients:

POST /api/tool-sessions/oauth/device/start
{"api_source_id":1}

Show the returned verification URI and user code to the business user. Poll GET /api/tool-sessions/{tool_session_id}/status no faster than the returned interval. Stop on ready, expired, failed, or revoked state.

Device codes and OAuth tokens are encrypted and never returned in status responses.

Authorization Code with PKCE

PKCE start is an administrator-browser operation:

POST /api/tool-sessions/oauth/pkce/start
{"api_source_id":1,"agent_id":2}

Open the returned authorization_url. The issuer redirects to GET /api/tool-sessions/oauth/pkce/callback?state=...&code=....

The callback atomically consumes the high-entropy state, exchanges the code, stores encrypted credentials, and sets the HTTP-only chat4openapi_tool_session cookie. State is single-use; transient secrets are erased on success, failure, expiry, or cancellation.

Pre-authorized Header or Cookie injection

Use injection when another authentication system has already obtained a supported credential:

POST /api/tool-sessions/credentials
{
  "api_source_id": 1,
  "headers": {"Authorization": "Bearer upstream-token"},
  "cookies": {},
  "expires_at": "2026-07-23T00:00:00Z"
}

The response exposes the opaque Tool Session token, never the injected credential. Unsafe transport headers, invalid characters, undeclared names, and raw Cookie headers are rejected.

Swagger login automation

Swagger login supports configured username/password login Tools through POST /v1/tool-sessions. The login Tool runs once, and its mapped Token, Header, or Cookie is scoped to that Tool's API source.

Declared expiry and JWT exp may only shorten the Session. Swagger login does not solve or bypass CAPTCHA, MFA, consent pages, or other interactive challenges; use Device Flow, PKCE, or external injection instead.

Browser login uses POST /api/tool-session/login, reads GET /api/tool-session/status, and revokes through POST /api/tool-session/logout. It stores only the opaque token in an HTTP-only cookie and still requires an administrator Tool Session owner.

Lifecycle and failure behavior

• GET /api/tool-sessions/{tool_session_id} returns owner-visible status.
• POST /api/tool-sessions/oauth/refresh explicitly refreshes OAuth credentials.
• DELETE /v1/tool-sessions/{tool_session_id} or DELETE /api/tool-sessions/{tool_session_id} revokes a Session.
• OAuth may refresh immediately before a Tool call and replay once after an upstream 401; it never starts an interactive authorization flow.
• No Tool Session returns tool_authorization_required when credentials are required.
• Expired or rejected credentials return tool_reauthorization_required.
• Revoking, expiring, or deleting an Agent key immediately invalidates its Sessions.
• Idle and absolute expiries are enforced before issuer or Tool network traffic.

Access and refresh tokens, client secrets, injected values, login passwords, Device codes, and PKCE verifiers are encrypted at rest, omitted from later responses, and never written to application logs.