# Authentication Methods

Author(s): [anna239](https://github.com/anna239)

## Elevator pitch

> What are you proposing to change?

I suggest adding more information about auth methods that agent supports, which will allow clients to draw more appropriate UI.

## Status quo

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

Agents have different ways of authenticating users: env vars with api keys, running a command like `<agent_name> login`, some just open a browser and use oauth.
[AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) does not really tell the client what should be done to authenticate. This means we can't show the user a control for entering key if an agent supports auth through env var.

Very few agents can authenticate fully on their own without user input, so agents with ACP auth support are limited in the methods they can offer, or require manual setup before being run as an ACP agent.

## What we propose to do about it

> What are you proposing to improve the situation?

We can add addition types of AuthMethods, to provide clients with additional information so they can assist in the login process.

## Shiny future

> How will things will play out once this feature exists?

It will be easier for end-users to start using an agent from inside the IDE as auth process will be more straightforward

## Implementation details and plan

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

I suggest adding following auth types:

1. Agent auth

Same as what there is now – agent handles the auth itself, this should be a default type if no type is provided for backward compatibility

```json  theme={null}
{
  "id": "123",
  "name": "Agent",
  "description": "Authenticate through agent",
  "type": "agent" // Optional/default value
}
```

2. Env variable

A user can enter a key and a client will pass it to the agent as an env variable

```json  theme={null}
{
  "id": "123",
  "name": "OpenAI api key",
  "description": "Provide your key",
  "type": "env_var",
  "varName": "OPEN_AI_KEY",
  "link": "OPTIONAL link to a page where user can get their key"
}
```

Since this would need to be supplied to the agent when the process is started, the client can check if it already passed such an env variable to the process, in which case the user can click on the button and the agent will read the already available key.

Otherwise, when the user clicks the button, the client could restart the agent process with the desired env variable, and then automatically send the authenticate message with the correct id to sign in for the user.

3. Terminal Auth

There have been experiments for a "terminal-auth" experience as a fallback. This requires the client to be able to run an interactive terminal for the user to login via a TUI.

```json  theme={null}
{
  "id": "123",
  "name": "Run in terminal",
  "description": "Setup Label",
  "type": "terminal",
  "args": ["--setup"],
  "env": { "VAR1": "value1", "VAR2": "value2" }
}
```

The `command` cannot be specified, the client will invoke the exact same binary with the exact same setup. The agent can supply additional arguments and environment variables as necessary. These will be supplied in **addition** to any args/env supplied by default when the server is started. So agents will need to have a way to kickoff their interactive login flow even if normal acp commands/arguments are supplied as well.

This is so that the agent doesn't need to know about the environment it is running in. It can't know the absolute path necessarily, and shouldn't be able to supply other commands or programs to minimize security issues.

### AuthErrors

It might be useful to include a list of AuthMethod ids to the AUTH\_REQUIRED JsonRpc error. Why do we need this if they're already shared during `initialize`:
All supported auth methods are shared during `initialize`. When user starts a session, they've already selected a model, which can narrow down a list of options.

```json  theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "Authentication required",
    "authMethods": [
      {
        "id": "chatgpt",
        "name": "Login with ChatGPT",
        "description": "Use your ChatGPT login with Codex CLI (requires a paid ChatGPT subscription)"
      }
    ]
  }
}
```

## Frequently asked questions

> What questions have arisen over the course of authoring this document or during subsequent discussions?

### What alternative approaches did you consider, and why did you settle on this one?

An alternative approach would be to include this information to an agent's declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289)

There is also an alternative to adding a separate `elicitation` capability, which is to create a separate auth type for this. Then the client can decide themselves if they support it or not.

## Revision history

There was a part about elicitations [https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx](https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx) removed it for now, will move to a separate rfd

* 2026-01-14: Updates based on Core Maintainer discussion


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://agentclientprotocol.com/llms.txt