diff --git a/docs/docs.json b/docs/docs.json index 8f7d3daad..727443ac2 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -82,6 +82,7 @@ "group": "Draft: In Progress and May Change", "hidden": true, "pages": [ + "protocol/draft/authentication", "protocol/draft/session-setup", "protocol/draft/session-list", "protocol/draft/session-delete", @@ -121,7 +122,6 @@ "rfds/mcp-over-acp", "rfds/session-usage", "rfds/auth-methods", - "rfds/logout-method", "rfds/session-delete", "rfds/diff-delete", "rfds/boolean-config-option", @@ -144,7 +144,7 @@ }, { "group": "Preview", - "pages": ["rfds/rust-sdk-v1"] + "pages": ["rfds/rust-sdk-v1", "rfds/logout-method"] }, { "group": "Completed", diff --git a/docs/protocol/draft/authentication.mdx b/docs/protocol/draft/authentication.mdx new file mode 100644 index 000000000..c8600d945 --- /dev/null +++ b/docs/protocol/draft/authentication.mdx @@ -0,0 +1,168 @@ +--- +title: "Authentication" +description: "Authenticating with agents and logging out" +--- + +ACP authentication is negotiated during [initialization](/protocol/initialization). Agents advertise available authentication methods in `authMethods`, Clients choose one by calling `authenticate`, and Agents that support ending an authenticated state advertise the draft `logout` capability. + + + The `logout` method and `agentCapabilities.auth.logout` capability are still + unstable and may change before they are stabilized. + + +
+ +```mermaid +sequenceDiagram + participant Client + participant Agent + + Client->>Agent: initialize + Agent-->>Client: initialize response (authMethods, auth.logout) + + alt Agent requires authentication + Client->>Agent: authenticate (methodId) + Agent-->>Client: authenticate response + end + + Note over Client,Agent: Authenticated requests may proceed + + alt User logs out + Client->>Agent: logout + Agent-->>Client: logout response + end + + Note over Client,Agent: New sessions require authentication again +``` + +
+ +## Advertising Authentication + +Agents advertise authentication options in the `authMethods` field of the `initialize` response. Each method has an `id` that the Client passes back to the Agent in a later `authenticate` request. + +Agents that support `logout` also advertise `agentCapabilities.auth.logout`: + +```json highlight={7-11,12-18} +{ + "jsonrpc": "2.0", + "id": 0, + "result": { + "protocolVersion": 1, + "agentCapabilities": { + "auth": { + "logout": {} + } + }, + "authMethods": [ + { + "id": "agent-login", + "name": "Agent login", + "description": "Sign in using the agent's login flow" + } + ] + } +} +``` + +If `agentCapabilities.auth.logout` is omitted or `null`, the Agent does not support `logout` and Clients **MUST NOT** call it. Supplying `{}` means the Agent supports the method. + +### Authentication method types + +The default authentication method type is `agent`, where the Agent handles authentication itself. When no `type` is present, the method is treated as `agent`: + +```json +{ + "id": "agent-login", + "name": "Agent login", + "description": "Sign in using the agent's login flow" +} +``` + +Draft authentication method types provide additional information so Clients can offer better UI: + +- `env_var`: the user provides credentials that the Client passes to the Agent as environment variables. +- `terminal`: the Client runs the Agent's terminal authentication flow for the user. + +`terminal` methods require Client support. Clients advertise this during initialization with `clientCapabilities.auth.terminal`: + +```json highlight={7-9} +{ + "jsonrpc": "2.0", + "id": 0, + "method": "initialize", + "params": { + "protocolVersion": 1, + "clientCapabilities": { + "auth": { + "terminal": true + } + } + } +} +``` + +See the [draft schema](/protocol/draft/schema#authmethod) for the full `AuthMethod` definitions. + +## Authenticating + +When an Agent requires authentication before allowing session creation, the Client calls `authenticate` with one of the advertised authentication method IDs: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "authenticate", + "params": { + "methodId": "agent-login" + } +} +``` + + + The ID of the authentication method to use. This value must match one of the + methods advertised in the `initialize` response. + + +On success, the Agent returns an empty result: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +After successful authentication, the Client can create new sessions without receiving an `auth_required` error for authentication-gated requests. + +## Logging Out + +The draft `logout` method allows Clients to end the current authenticated state. Clients should only call it after verifying the Agent advertised `agentCapabilities.auth.logout` during initialization. + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "logout", + "params": {} +} +``` + +On success, the Agent returns an empty result: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": {} +} +``` + +After a successful `logout`, new sessions that require authentication will require the Client to call `authenticate` again. + +## Active Sessions + +The protocol does not guarantee what happens to already-running sessions after `logout`. Agents may terminate them, keep them running, or return `auth_required` errors for future session activity. + +Clients **SHOULD** be prepared for active session operations to fail with authentication-related errors after logout and should prompt the user to authenticate again when appropriate. diff --git a/docs/protocol/draft/session-setup.mdx b/docs/protocol/draft/session-setup.mdx index f3d9fbb66..cdc46b65c 100644 --- a/docs/protocol/draft/session-setup.mdx +++ b/docs/protocol/draft/session-setup.mdx @@ -7,6 +7,8 @@ Sessions represent a specific conversation or thread between the [Client](/proto Before creating a session, Clients **MUST** first complete the [initialization](/protocol/initialization) phase to establish protocol compatibility and capabilities. +If the Agent requires authentication, `session/new` may fail with an `auth_required` error until the Client completes the [authentication flow](/protocol/draft/authentication). +
```mermaid diff --git a/docs/rfds/logout-method.mdx b/docs/rfds/logout-method.mdx index 932205dad..0635768c9 100644 --- a/docs/rfds/logout-method.mdx +++ b/docs/rfds/logout-method.mdx @@ -207,4 +207,5 @@ The RFD intentionally does not mandate a specific behavior to allow flexibility. ## Revision history +- 2026-05-17: Moved to Preview. - 2026-02-02: Initial draft diff --git a/docs/rfds/updates.mdx b/docs/rfds/updates.mdx index 0af82becb..05e15401a 100644 --- a/docs/rfds/updates.mdx +++ b/docs/rfds/updates.mdx @@ -6,6 +6,13 @@ rss: true This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates). + +## Logout Method RFD moves to Preview stage + +The RFD for adding a `logout` method to the protocol has been moved to Preview stage. Please review the [RFD](/rfds/logout-method) for more information on the current proposal and provide feedback before the feature is stabilized. + + + ## Rust SDK based on SACP RFD moves to Preview stage