> For the complete documentation index, see [llms.txt](https://docs.worldlibertyfinancial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.worldlibertyfinancial.com/agentpay-sdk/workflows/agent-auth.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.