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:

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:

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:

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:

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 for details.

Rotate or revoke

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

agentpay config agent-auth rotate

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

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:

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.