Authentication

The NextPay CLI uses agent-auth — a cryptographic authentication flow built on Better Auth's agent plugin. Instead of API keys or session tokens, the CLI registers an Ed25519 keypair with the NextPay identity service and signs each request with a fresh JWT. No long-lived secrets are stored.

Agent-auth flow

When you run nextpay auth login, the CLI goes through a four-step process:

1. Discovery

The CLI fetches the identity service configuration from:

GET /.well-known/agent-configuration

This returns the identity service base URL and the supported agent-auth endpoints. The CLI uses this to know where to register and where to poll for device authorization.

2. Registration

The CLI generates a fresh Ed25519 keypair locally and registers the public key with the identity service:

nextpay --env dev auth login

The identity service assigns the CLI an agent ID and associates the public key with your user account (after the device authorization step).

3. Device authorization

The CLI opens the browser-based device authorization flow. You will see a URL and a short code in your terminal:

Visit https://identity.nextpay.world/agent/authorize?code=ABCD-1234
and confirm the request to link this agent.

1. Open the URL in your browser.
2. Review the agent name and requested capabilities.
3. Approve the request.

The CLI polls for completion and receives confirmation once you approve. No code is copy-pasted — the CLI and identity service coordinate automatically.

4. Credentials stored locally

After approval, the CLI stores two files under ~/.config/nextpay/<env>/:

Authenticated requests

On every API call, the CLI:

1. Loads the private key from agent.key.
2. Signs a fresh JWT (short-lived, single-use) with the Ed25519 key.
3. Sends the JWT as a Bearer token in the Authorization header.

The JWT is never reused. There is no stored session token or API key to rotate or revoke.

Capabilities

Agents inherit the permissions of the user who approved them, scoped to the organization and workspace specified during login. You can inspect what a registered agent is allowed to do:

GET /v1/agent/capabilities

This returns the list of capabilities the identity service has granted to the current agent. Capabilities are determined by the user's role in the organization — not by any key configuration. To restrict an agent, adjust the user's role in the NextPay dashboard under Settings > Team.

Check authentication status

nextpay --env dev auth status

This shows the agent ID, linked user, mode, organization, and workspace.

Log out

nextpay --env dev auth logout

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

Environment selection

The --env flag selects which NextPay environment to connect to:

• --env dev — Development environment (for testing)
• --env prod — Production environment (real money)

You can also set this via the NEXTPAY_ENV environment variable to avoid repeating it on every command.