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