Auth Commands

The auth command group manages authentication with the NextPay platform using the agent-auth flow. See Authentication for a full explanation of how it works.

auth login

Register this CLI as an agent and link it to your NextPay account via browser-based device authorization.

nextpay --env dev auth login

What happens:

1. The CLI discovers the identity service via /.well-known/agent-configuration.
2. A fresh Ed25519 keypair is generated and the public key is registered with the identity service.
3. The CLI prints a URL and a short code. Open the URL in your browser and approve the agent request.
4. After approval, credentials are stored at ~/.config/nextpay/<env>/agent.json and agent.key.

Each auth login creates a new agent registration. Multiple agents can be active simultaneously (e.g., one per environment or per machine).

auth logout

Remove locally stored agent credentials for the current environment.

nextpay --env dev auth logout

This deletes agent.json and agent.key for the specified environment. Credentials for other environments are not affected.

To also invalidate the agent server-side (so the private key can never be used again even if recovered), revoke the agent via:

DELETE /v1/agent/<agentId>

auth status

Show the current authentication state for the specified environment.

nextpay --env dev auth status

Example output:

{
  "authenticated": true,
  "agentId": "agent_abc123",
  "user": {"id": "user_xyz789", "email": "juan@example.com", "name": "Juan Dela Cruz"},
  "mode": "agent",
  "organization": {"id": "org_def456", "name": "Acme Corp"},
  "workspace": {"id": "ws_ghi012", "name": "Finance"}
}

If no credentials are found, authenticated will be false and the other fields will be absent.