# Agent auth

Agent auth is the local credential the CLI uses to authenticate against the managed wallet runtime. These commands are for maintenance, not part of the normal transfer flow.

In the current macOS-first flow, the preferred storage location is macOS Keychain. Avoid storing this material in plaintext configuration or shell history.

## Auth token resolution order

When a command needs the agent auth token, the CLI resolves it in this priority order:

1. `--agent-auth-token-stdin` (preferred; secure pipe input)
2. macOS Keychain (automatic lookup by agent key id)
3. `--agent-auth-token` flag (warns about shell history exposure)
4. `agentAuthToken` field in `config.json` (deprecated; requires `--allow-legacy-agent-auth-source`)
5. `AGENTPAY_AGENT_AUTH_TOKEN` environment variable (deprecated; requires `--allow-legacy-agent-auth-source`)

The first source that returns a value wins. Sources 3–5 print a warning to stderr.

## Check status

Use this to see whether the current machine has agent auth stored for the configured agent key:

```bash
agentpay config agent-auth status --json
```

## Set or import agent auth

If you need to store agent auth explicitly, prefer stdin over a visible command-line flag:

```bash
agentpay config agent-auth set \
  --agent-key-id <UUID> \
  --agent-auth-token-stdin
```

If you have a private bootstrap JSON output from admin setup, import it instead:

```bash
agentpay config agent-auth import <PATH_TO_BOOTSTRAP_JSON> --json
```

By default, the source file is **redacted** after import. Use `--keep-source` to leave the source file intact (prints a security warning), or `--delete-source` to delete the source file entirely instead of redacting it.

## Migrate legacy config storage

If older state left `agentAuthToken` in `config.json`, migrate it into Keychain:

```bash
agentpay config agent-auth migrate --json
```

This is the supported cleanup path for legacy plaintext storage. If the Keychain already holds a different token for the same agent key ID, migration will fail unless you pass `--overwrite-keychain`.

`agentpay repair` also performs this same migration automatically as part of its general health fixes. See [Troubleshooting](/agentpay-sdk/workflows/troubleshooting.md) for details.

## Rotate or revoke

Rotate when you want to replace the current credential but keep the wallet attachment in place:

```bash
agentpay config agent-auth rotate
```

Revoke when the current agent key and its bearer token should no longer be trusted:

```bash
agentpay config agent-auth revoke
```

Both commands can prompt for the vault password locally.

## Clear local storage only

If you only want to remove the locally stored Keychain token without revoking the agent key on the daemon side, use:

```bash
agentpay config agent-auth clear --json
```

This is different from `revoke`. `clear` removes local storage only - specifically, the Keychain token, `agentKeyId` from config, and any legacy `agentAuthToken` from config. `revoke` invalidates the agent key on the daemon side and removes local credentials as part of the revocation path.

## Next step

If you need to clean up or remove the SDK entirely, continue to [Reset and uninstall](/agentpay-sdk/workflows/reset-and-uninstall.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.worldlibertyfinancial.com/agentpay-sdk/workflows/agent-auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.