> ## Documentation Index
> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Authentication State Query

* Author(s): [@xtmq](https://github.com/xtmq)
* Champion: [@benbrandt](https://github.com/benbrandt)

## Elevator pitch

> What are you proposing to change?

Add an `auth/status` method and corresponding capability that allows clients to query the agent's current authentication state. This lets clients determine whether the agent is already configured with valid credentials or requires authorization before creating a session, without relying on the ambiguous error behavior of `session/new`.

## Status quo

> How do things work today and what problems does this cause? Why would we change things?

Currently, there is no dedicated way for a client to determine whether an agent has valid authentication configured. The typical workaround is:

1. Call `initialize`
2. Call `session/new`
3. If the agent has no credentials, it *may* return an authorization error
4. The client handles the error and initiates an authorization flow

This approach has significant problems:

* **Unreliable detection**: The `session/new` method is not required by the specification to check authorization. Some agents validate credentials eagerly, others do so lazily (e.g., on the first LLM call). The client cannot rely on `session/new` to consistently surface auth issues.
* **Wasted resources**: Creating a session only to discard it on auth failure is wasteful, especially if session creation has side effects (resource allocation, logging, history file creation, etc.).
* **Poor user experience**: The client cannot proactively guide the user through authorization before session creation. Instead, users encounter errors mid-flow.

## Shiny future

> How will things play out once this feature exists?

Clients will be able to:

1. Discover whether an agent supports auth state queries via capabilities during initialization
2. Query the agent's current authentication state immediately after initialization
3. Make an informed decision about whether to proceed with session creation, initiate an authorization flow, or configure endpoints (e.g., via `setLlmEndpoints`)
4. Provide clear, proactive UX — e.g., showing a "Sign in" prompt before any session is created
5. Completely skip authentication process if the agent is already authenticated

## Implementation details and plan

> Tell me more about your implementation. What is your detailed implementation plan?

### Intended flow

The client calls `initialize`, inspects capabilities to confirm `auth/status` support, then queries auth state before deciding how to proceed.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Agent

    Client->>Agent: initialize
    Note right of Agent: Agent reports capabilities,<br/>including auth/status support
    Agent-->>Client: initialize response<br/>(agentCapabilities.auth.status)

    Client->>Agent: auth/status
    Agent-->>Client: auth/status response<br/>(authenticated, message)

    alt Authenticated
        Client->>Agent: session/new
    else Not authenticated
        Note over Client: Client initiates<br/>authorization flow<br/>(e.g., call authenticate, setLlmEndpoints)
        Client->>Agent: authenticate
        Client->>Agent: session/new
    end
```

1. **Initialization**: The client calls `initialize`. The agent responds with capabilities, including `auth/status` support via `agentCapabilities.auth`.
2. **Auth state query**: The client calls `auth/status`. The agent inspects its local configuration, stored credentials, or environment to determine the current auth state.
3. **Client-side decision**: Based on the response, the client either proceeds to session creation or initiates an authorization flow first.

### Capability advertisement

The agent advertises support for the `auth/status` method via the existing `auth` capability in `agentCapabilities`:

```typescript theme={null}
interface AuthCapabilities {
  // ... existing fields (e.g., terminal) ...

  /**
   * Auth status query support.
   * If true, the agent supports the auth/status method.
   */
  status?: boolean;
}
```

**Initialize Response example:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentInfo": {
      "name": "MyAgent",
      "version": "2.0.0"
    },
    "agentCapabilities": {
      "auth": {
        "status": true
      },
      "sessionCapabilities": {}
    }
  }
}
```

### `auth/status` method

A method that can be called after initialization to query the agent's current authentication state.

```typescript theme={null}
interface AuthStatusRequest {
  /** Extension metadata */
  _meta?: Record<string, unknown>;
}

interface AuthStatusResponse {
  /**
   * Whether the agent has credentials configured.
   * true means credentials are present (validity is not guaranteed).
   * false means no credentials are configured.
   */
  authenticated: boolean;

  /** Human-readable description of the overall auth state */
  message?: string;

  /** Extension metadata */
  _meta?: Record<string, unknown>;
}
```

#### JSON Schema Additions

```json theme={null}
{
  "$defs": {
    "AuthStatusResponse": {
      "description": "Response to auth/status method.",
      "properties": {
        "authenticated": {
          "type": "boolean",
          "description": "Whether the agent has credentials configured."
        },
        "message": {
          "type": ["string", "null"],
          "description": "Human-readable description of the overall auth state."
        },
        "_meta": {
          "additionalProperties": true,
          "type": ["object", "null"]
        }
      },
      "required": ["authenticated"],
      "type": "object"
    }
  }
}
```

#### Example Exchange

**auth/status Request:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "auth/status",
  "params": {}
}
```

**auth/status Response (authenticated):**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "authenticated": true,
    "message": "Credentials are configured"
  }
}
```

**auth/status Response (unauthenticated):**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "authenticated": false,
    "message": "No credentials configured. Please provide API keys or configure an LLM endpoint."
  }
}
```

#### Behavior

1. **Capability advertisement**: The agent SHOULD include `auth.status` in `agentCapabilities` if it supports the `auth/status` method. Clients MUST check for this capability before calling the method.

2. **Timing**: The `auth/status` method MUST be callable after `initialize`. It MAY be called multiple times (e.g., after `authenticate`, to re-check state).

3. **Local checks only**: The agent MAY determine auth state based on locally available information (config files, environment variables, stored tokens) or by making external API calls. `authenticated: true` means credentials are present, NOT that they are guaranteed to be valid.

4. **No side effects**: Calling `auth/status` MUST NOT modify any agent state. It is a pure query.

5. **Aggregate response**: The response includes only top-level `authenticated` and optional `message`, keeping the API surface minimal and avoiding per-method complexity.

## Frequently asked questions

> What questions have arisen over the course of authoring this document?

### Why not rely on `session/new` errors?

The `session/new` method is designed for session creation, not for auth validation. Per the specification, agents are not required to validate credentials during session creation — some agents defer validation to the first actual LLM call. This means a successful `session/new` does not guarantee the agent is authenticated, and a failed `session/new` may fail for reasons unrelated to authentication. A dedicated method provides a clear, unambiguous signal.

### Why not include auth state in the `initialize` response directly?

The `initialize` response contains capabilities — what the agent *supports*. Auth state is runtime information — what the agent *currently has configured*. Mixing these concerns would make `initialize` less predictable. Additionally, auth state may change after initialization (e.g., after a `setLlmEndpoints` call), and a separate method allows re-querying.

### Why not just check for the presence of environment variables on the client side?

Agents may obtain credentials from many sources: config files, keychains, OAuth tokens, environment variables, or even embedded keys. The client has no visibility into these mechanisms. Only the agent knows whether it has usable credentials configured.

### Why did we remove additional auth details from `auth/status` for now?

Extra fields (such as per-auth-method state or "which auth method was used") are not consistently well-defined across agents. In practice, one auth flow can enable multiple credential types (for example, terminal login resulting in an API key), so a strict 1:1 mapping can be ambiguous and potentially misleading for clients.

To avoid locking in confusing semantics, the proposal currently keeps `auth/status` minimal and reliable: top-level `authenticated` plus optional `message`. This solves the immediate UX and control-flow problem while preserving room to add richer, standardized details later once cross-agent semantics are clearer.

## Revision history

* 2026-07-21: Accepted as a Draft RFD
* 2026-03-15: Remove `authMethods` from the proposal and keep aggregate auth state only (`authenticated` + optional `message`)
* 2026-03-10: Rename `getAuthState` to `auth/status`, nest capability under `agentCapabilities.auth`
* 2026-03-07: Address review feedback on auth state structure
* 2026-03-05: Initial draft — preliminary proposal to start discussion