|
| 1 | +--- |
| 2 | +title: "Authentication" |
| 3 | +description: "Authenticating with agents and logging out" |
| 4 | +--- |
| 5 | + |
| 6 | +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. |
| 7 | + |
| 8 | +<Note> |
| 9 | + The `logout` method and `agentCapabilities.auth.logout` capability are still |
| 10 | + unstable and may change before they are stabilized. |
| 11 | +</Note> |
| 12 | + |
| 13 | +<br /> |
| 14 | + |
| 15 | +```mermaid |
| 16 | +sequenceDiagram |
| 17 | + participant Client |
| 18 | + participant Agent |
| 19 | +
|
| 20 | + Client->>Agent: initialize |
| 21 | + Agent-->>Client: initialize response (authMethods, auth.logout) |
| 22 | +
|
| 23 | + alt Agent requires authentication |
| 24 | + Client->>Agent: authenticate (methodId) |
| 25 | + Agent-->>Client: authenticate response |
| 26 | + end |
| 27 | +
|
| 28 | + Note over Client,Agent: Authenticated requests may proceed |
| 29 | +
|
| 30 | + alt User logs out |
| 31 | + Client->>Agent: logout |
| 32 | + Agent-->>Client: logout response |
| 33 | + end |
| 34 | +
|
| 35 | + Note over Client,Agent: New sessions require authentication again |
| 36 | +``` |
| 37 | + |
| 38 | +<br /> |
| 39 | + |
| 40 | +## Advertising Authentication |
| 41 | + |
| 42 | +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. |
| 43 | + |
| 44 | +Agents that support `logout` also advertise `agentCapabilities.auth.logout`: |
| 45 | + |
| 46 | +```json highlight={7-11,12-18} |
| 47 | +{ |
| 48 | + "jsonrpc": "2.0", |
| 49 | + "id": 0, |
| 50 | + "result": { |
| 51 | + "protocolVersion": 1, |
| 52 | + "agentCapabilities": { |
| 53 | + "auth": { |
| 54 | + "logout": {} |
| 55 | + } |
| 56 | + }, |
| 57 | + "authMethods": [ |
| 58 | + { |
| 59 | + "id": "agent-login", |
| 60 | + "name": "Agent login", |
| 61 | + "description": "Sign in using the agent's login flow" |
| 62 | + } |
| 63 | + ] |
| 64 | + } |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +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. |
| 69 | + |
| 70 | +### Authentication method types |
| 71 | + |
| 72 | +The default authentication method type is `agent`, where the Agent handles authentication itself. When no `type` is present, the method is treated as `agent`: |
| 73 | + |
| 74 | +```json |
| 75 | +{ |
| 76 | + "id": "agent-login", |
| 77 | + "name": "Agent login", |
| 78 | + "description": "Sign in using the agent's login flow" |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +Draft authentication method types provide additional information so Clients can offer better UI: |
| 83 | + |
| 84 | +- `env_var`: the user provides credentials that the Client passes to the Agent as environment variables. |
| 85 | +- `terminal`: the Client runs the Agent's terminal authentication flow for the user. |
| 86 | + |
| 87 | +`terminal` methods require Client support. Clients advertise this during initialization with `clientCapabilities.auth.terminal`: |
| 88 | + |
| 89 | +```json highlight={7-9} |
| 90 | +{ |
| 91 | + "jsonrpc": "2.0", |
| 92 | + "id": 0, |
| 93 | + "method": "initialize", |
| 94 | + "params": { |
| 95 | + "protocolVersion": 1, |
| 96 | + "clientCapabilities": { |
| 97 | + "auth": { |
| 98 | + "terminal": true |
| 99 | + } |
| 100 | + } |
| 101 | + } |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +See the [draft schema](/protocol/draft/schema#authmethod) for the full `AuthMethod` definitions. |
| 106 | + |
| 107 | +## Authenticating |
| 108 | + |
| 109 | +When an Agent requires authentication before allowing session creation, the Client calls `authenticate` with one of the advertised authentication method IDs: |
| 110 | + |
| 111 | +```json |
| 112 | +{ |
| 113 | + "jsonrpc": "2.0", |
| 114 | + "id": 1, |
| 115 | + "method": "authenticate", |
| 116 | + "params": { |
| 117 | + "methodId": "agent-login" |
| 118 | + } |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +<ParamField path="methodId" type="string" required> |
| 123 | + The ID of the authentication method to use. This value must match one of the |
| 124 | + methods advertised in the `initialize` response. |
| 125 | +</ParamField> |
| 126 | + |
| 127 | +On success, the Agent returns an empty result: |
| 128 | + |
| 129 | +```json |
| 130 | +{ |
| 131 | + "jsonrpc": "2.0", |
| 132 | + "id": 1, |
| 133 | + "result": {} |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +After successful authentication, the Client can create new sessions without receiving an `auth_required` error for authentication-gated requests. |
| 138 | + |
| 139 | +## Logging Out |
| 140 | + |
| 141 | +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. |
| 142 | + |
| 143 | +```json |
| 144 | +{ |
| 145 | + "jsonrpc": "2.0", |
| 146 | + "id": 2, |
| 147 | + "method": "logout", |
| 148 | + "params": {} |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +On success, the Agent returns an empty result: |
| 153 | + |
| 154 | +```json |
| 155 | +{ |
| 156 | + "jsonrpc": "2.0", |
| 157 | + "id": 2, |
| 158 | + "result": {} |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +After a successful `logout`, new sessions that require authentication will require the Client to call `authenticate` again. |
| 163 | + |
| 164 | +## Active Sessions |
| 165 | + |
| 166 | +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. |
| 167 | + |
| 168 | +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. |
0 commit comments