Agent Security Best Practices

The agent-auth flow is designed to be secure by default — short-lived JWTs, no stored secrets beyond the private key, and capability scoping via user roles. Follow these additional practices to keep your agents secure.

Protect the private key file

The CLI stores the Ed25519 private key at ~/.config/nextpay/<env>/agent.key with 0600 permissions. Keep it there:

• Do not copy agent.key into Docker images, repositories, or shared filesystems.
• Do not log or print the key contents.
• On CI systems, use ephemeral runners so the key is discarded after each run. Re-run nextpay auth login for each fresh environment.

Use least-privilege roles

Approve agents under accounts that have only the roles the agent needs:

Avoid approving agents under admin accounts unless the agent genuinely needs administrative access.

One agent per purpose

Each nextpay auth login produces a distinct agent ID. Use separate agent registrations for:

• Each environment (dev vs. prod)
• Each logical agent or service (e.g., reporting bot vs. disbursement agent)

This makes it straightforward to revoke a single agent without affecting others.

Revoke stale agents

Periodically audit registered agents in the identity service and revoke any that are no longer active. Unlike API keys, agents are identifiable by their agent ID and the user who approved them, making audits easier.

Monitor with audit logs

Review audit logs to verify agents are behaving as expected:

nextpay --env prod audit list --limit 50

Each action is attributed to the agent ID, so you can trace which agent performed which operation. If you see unexpected actions, revoke the agent immediately.