Skip to main content
ACP authentication is negotiated during initialization. Agents advertise available authentication methods in authMethods. Clients use auth/login and auth/logout only when the Agent advertises the authentication surface.

​
Advertising Authentication

Agents advertise authentication options in the authMethods field of the initialize response. Each method has a methodId that the Client passes back to the Agent in a later auth/login request. Returning one or more valid entries in authMethods advertises the authentication surface. An Agent that does so MUST implement both auth/login and auth/logout. If authMethods is omitted or empty, the Agent does not advertise this surface and Clients MUST NOT call either method. capabilities.auth is orthogonal to this requirement. It advertises authentication-related extensions, not the availability of the baseline auth/login and auth/logout methods.
Because this response contains a valid authentication method, the Agent must support both auth/login and auth/logout.

​
Authentication method types

The standard authentication method type is agent, where the Agent handles authentication itself. Every authentication method must include a type discriminator:
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.
Authentication method type values can be custom or future variants. Custom method types MUST begin with _. Unknown non-underscore method types are reserved for future ACP variants. Clients that do not understand a method type should preserve the raw method payload when storing, replaying, proxying, or forwarding initialization data, and otherwise ignore the method or display it generically. terminal authentication methods require Client support. Clients advertise this during initialization with capabilities.auth.terminal:
If capabilities.auth.terminal is omitted or null, the Client does not advertise support for terminal authentication methods. Supplying {} means the Client supports terminal authentication methods. See the draft schema for the full AuthMethod definitions.

​
Authenticating

When an Agent has advertised the authentication surface and requires authentication before allowing session creation, the Client calls auth/login with one of the advertised authentication method IDs:
​
methodId
string
required
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:
After successful authentication, the Client can create new sessions without receiving an auth_required error for authentication-gated requests.

​
Logging Out

The auth/logout method allows Clients to end the current authenticated state. Clients may call it only when the Agent advertised one or more valid authentication methods during initialization; there is no separate logout capability marker.
On success, the Agent returns an empty result:
After a successful auth/logout, new sessions that require authentication will require the Client to call auth/login again.

​
Active Sessions

The protocol does not guarantee what happens to already-running sessions after auth/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.