CLI Authentication

The CLI supports three authentication methods: interactive browser login, API key, and merchant JWT (email/password).

Interactive Login (recommended)

Opens your browser for OAuth-based authentication:

ikw auth login

Options:

Flag	Default	Description
--port <n>	8765	Local callback server port
--no-browser		Don't open browser automatically (prints URL instead)

The CLI starts a local HTTP server, opens your browser to the Ikawaari login page, and receives the token via callback.

API Key Login

Store an API key for direct API access:

ikw auth login:manual --api-key ik_test_your_key_here

Merchant JWT Login

Authenticate with email and password:

# Password via flag (not recommended — visible in shell history)
ikw auth login:manual --email you@example.com --password your_password

# Password via stdin (recommended)
echo "your_password" | ikw auth login:manual --email you@example.com --password-stdin

Ops Token

For platform operators with admin access:

ikw auth login:manual --ops-token ops_admin_token --ops-merchant-id <merchant-guid>

Target a Specific Environment

By default, credentials are stored for the current environment. Override with --environment:

ikw auth login:manual --api-key ik_live_xxx --environment live

Check Current Identity

ikw auth whoami

# JSON output
ikw auth whoami --json

{
  "email": "you@example.com",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Logout

Clear stored credentials for the current environment:

ikw auth logout

# Or for a specific environment
ikw auth logout --environment live

How Credentials Are Stored

Credentials are stored in a local JSON config file:

OS	Path
Linux	~/.config/ikw/config.json
macOS	~/Library/Application Support/ikw/config.json
Windows	%APPDATA%\ikw\config.json

attention

The config file contains sensitive credentials. Do not commit it to version control or share it.

Authentication Priority

When making API requests, the CLI uses credentials in this order:

1. Merchant JWT — Used for dashboard-level operations
2. API Key — Used for API-level operations
3. Ops Token — Used for operator/admin commands

Some commands require a specific auth method (e.g., webhooks requires an API key, payments refund requires a merchant JWT).