Authentication CLI

Command-line tool that provides a complete authentication workflow including user registration, login, Multi-Factor Authentication (MFA), and API key management.

Complete How-To Guide

Features

User Registration - Create new accounts with email verification
Login & Authentication - Secure login with access/refresh tokens
Multi-Factor Authentication (MFA) - Optional two-factor authentication for enhanced security
Account Verification - Verify email addresses with verification codes
API Key Management - Create and revoke API keys for programmatic access
Token Persistence - Save tokens securely for seamless authentication
Token Refresh - Automatically refresh expired access tokens
User Information - Display current user details with whoami

Prerequisites

Go 1.19 or higher (for building from source)
Valid email address for registration
Internet connection
Operating System: Linux, macOS, or Windows

Installation

Option 1: Download Pre-built Binary

Download the latest release for your platform from the releases page.

# Linux/macOS
curl -L https://github.com/koneksi/auth-cli/releases/latest/download/koneksi-auth-$(uname -s)-$(uname -m).tar.gz | tar xz
sudo mv koneksi-auth /usr/local/bin/
chmod +x /usr/local/bin/koneksi-auth

# Verify installation
koneksi-auth --version

Option 2: Install from Source

# Clone the repository
git clone https://github.com/koneksi/auth-cli.git
cd koneksi-auth-cli

# Build the binary
make build

# Install to system
sudo make install

# Or manually move to PATH
sudo mv koneksi-auth /usr/local/bin/

Option 3: Using Go Install

go install github.com/koneksi/auth-cli/cmd/koneksi-auth@latest

Getting Started

Basic Command Structure

koneksi-auth [command] [flags]

Global Flags

--base-url string: Override the API base URL (default: https://uat.koneksi.co.kr)
--config string: Config file path (default: ~/.koneksi-auth/config.yaml)
-o, --output string: Output format (text, json)
-h, --help: Show help information

View Available Commands

koneksi-auth --help

User Registration

Step 1: Create a New Account

koneksi-auth register \
  --first-name "John" \
  --last-name "Doe" \
  --email "john.doe@example.com" \
  --password "SecurePassword123!"

Optional fields:

--middle-name: Middle name
--suffix: Name suffix (Jr., Sr., etc.)

Example Output

Registration successful!
User ID: 123e4567-e89b-12d3-a456-426614174000
Email: john.doe@example.com

IMPORTANT: A verification code has been sent to your email.

Next steps:
1. Check your email for the verification code
2. Login: koneksi-auth login -e john.doe@example.com -p <your-password>
3. Verify: koneksi-auth verify <verification-code> -t <access-token>

Account Verification

After registration, you must verify your email address before creating API keys.

koneksi-auth login \
  --email "john.doe@example.com" \
  --password "SecurePassword123!"

Save the access token from the output.

Step 2: Verify Your Account

Check your email for the 6-digit verification code, then:

koneksi-auth verify 123456 --token "your-access-token"

Example Output

Account verified successfully!
Email: john.doe@example.com
Verified: true

You can now create API keys using:
  koneksi-auth create-key "My API Key" -t <your-access-token>

koneksi-auth login \
  --email "john.doe@example.com" \
  --password "SecurePassword123!"

Save Tokens to Config

Use the --save flag to store tokens in your config file:

koneksi-auth login \
  --email "john.doe@example.com" \
  --password "SecurePassword123!" \
  --save

Login successful!

Access Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Use this token to create/revoke API keys:
  koneksi-auth create-key "My API Key" -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Refresh Token (save for later use):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Multi-Factor Authentication (MFA)

MFA adds an extra layer of security to your account using Time-based One-Time Passwords (TOTP).

Setting Up MFA

Step 1: Generate MFA Secret

koneksi-auth mfa-setup --token "your-access-token"

Output:

MFA Setup Generated!

Secret Key: JBSWY3DPEHPK3PXP
Add this secret to your authenticator app (Google Authenticator, Authy, etc.)

QR Code URL: https://uat.koneksi.co.kr/qr/mfa/...
Or scan the QR code at the URL above

After adding to your authenticator app, enable MFA with:
  koneksi-auth mfa-enable <otp-code> -t <your-access-token>

Step 2: Add to Authenticator App

Open your authenticator app (Google Authenticator, Authy, 1Password, etc.)
Add a new account
Either:
- Scan the QR code from the provided URL
- Manually enter the secret key

Step 3: Enable MFA

Get the 6-digit code from your authenticator app and enable MFA:

koneksi-auth mfa-enable 123456 --token "your-access-token"

Output:

MFA has been enabled successfully!

IMPORTANT: Save your recovery codes in a safe place.
You will need to use MFA for all future logins.

When MFA is enabled, login becomes a two-step process:

Step 1: Initial Login

koneksi-auth login \
  --email "john.doe@example.com" \
  --password "SecurePassword123!"

Output:

MFA Required!
Login Code: C7EFADA944BB

Please enter your MFA OTP code to complete login:
  koneksi-auth verify-otp C7EFADA944BB <otp-code>

Step 2: Complete Login with OTP

Get the current 6-digit code from your authenticator app:

koneksi-auth verify-otp C7EFADA944BB 654321

Output:

MFA verification successful!

Access Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Use this token to create/revoke API keys:
  koneksi-auth create-key "My API Key" -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Disabling MFA

To disable MFA, you need your account password:

koneksi-auth mfa-disable \
  --password "SecurePassword123!" \
  --token "your-access-token"

Output:

MFA has been disabled successfully!
You can re-enable it anytime using 'mfa-setup' and 'mfa-enable' commands.

API Key Management

API keys (service accounts) are used for programmatic access to Koneksi services.

Create an API Key

koneksi-auth create-key "Production API" --token "your-access-token"

Output:

API Key 'Production API' created successfully!

Client ID:
ck_1234567890abcdef

Client Secret (save this, it won't be shown again):
cs_abcdef1234567890abcdef1234567890

To use these credentials with koneksi-backup:
  export KONEKSI_API_CLIENT_ID=ck_1234567890abcdef
  export KONEKSI_API_CLIENT_SECRET=cs_abcdef1234567890abcdef1234567890

Or add them to your config file (~/.koneksi-backup/config.yaml)

List Your API Keys

koneksi-auth list-keys --token "your-access-token"

Revoke an API Key

koneksi-auth revoke-key "ck_1234567890abcdef" --token "your-access-token"

Output:

API Key 'ck_1234567890abcdef' has been revoked successfully.

Configuration

Configuration File

The CLI uses a YAML configuration file located at ~/.koneksi-auth/config.yaml:

auth:
  base_url: https://uat.koneksi.co.kr
  access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  client_id: ck_1234567890abcdef
  client_secret: cs_abcdef1234567890abcdef1234567890

Environment Variables

You can also use environment variables:

export KONEKSI_AUTH_BASE_URL=https://uat.koneksi.co.kr
export KONEKSI_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
export KONEKSI_AUTH_REFRESH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Priority Order

Command-line flags (highest priority)
Environment variables
Configuration file
Default values

Advanced Usage

Using Different Environments

Development Environment

koneksi-auth login \
  --base-url https://dev.koneksi.co.kr \
  --email "dev@example.com" \
  --password "password" \
  --save

Production Environment

Create a separate config file:

koneksi-auth login \
  --config ~/.koneksi-auth/prod.yaml \
  --base-url https://api.koneksi.co.kr \
  --email "prod@example.com" \
  --password "password" \
  --save

JSON Output for Scripting

Use -o json for machine-readable output:

koneksi-auth login -e user@example.com -p password -o json | jq -r '.data.access_token'

Refresh Expired Tokens

koneksi-auth refresh --refresh-token "your-refresh-token"

Check Current User

koneksi-auth whoami --token "your-access-token"

Troubleshooting

Common Issues

1. "Authentication token required" Error

Solution: Provide the access token using one of these methods:

Command flag: -t "your-token"
Environment variable: export KONEKSI_AUTH_TOKEN="your-token"
Config file with saved token

2. "Account not verified" Error

Solution: Complete email verification:

koneksi-auth verify <code> -t <token>

3. MFA Code Invalid

Possible causes:

Time sync issue: Ensure your device time is accurate
Wrong code: Make sure you're using the current 6-digit code
Wrong account: Verify you're using the correct authenticator entry

4. Token Expired

Solution: Use the refresh token to get a new access token:

koneksi-auth refresh -r "your-refresh-token"

Debug Mode

For verbose output, set the log level:

export KONEKSI_LOG_LEVEL=debug
koneksi-auth login -e user@example.com -p password

Getting Help

Command help: koneksi-auth [command] --help
GitHub Issues: https://github.com/koneksi/auth-cli/issues
Documentation: https://docs.koneksi.co.kr

Security Best Practices

Never share your tokens or API credentials
Use environment variables in CI/CD pipelines instead of hardcoding credentials
Enable MFA for enhanced account security
Rotate API keys regularly
Store config files with restricted permissions: chmod 600 ~/.koneksi-auth/config.yaml
Use separate API keys for different applications/environments
Revoke unused API keys promptly

Complete Workflow Example

Here's a complete example from registration to API usage:

# 1. Register new account
koneksi-auth register \
  --first-name "Jane" \
  --last-name "Smith" \
  --email "jane.smith@example.com" \
  --password "SuperSecure123!"

# 2. Login
koneksi-auth login \
  --email "jane.smith@example.com" \
  --password "SuperSecure123!" \
  --save

# 3. Verify account (check email for code)
koneksi-auth verify 654321

# 4. Setup MFA (optional but recommended)
koneksi-auth mfa-setup
# Add secret to authenticator app
koneksi-auth mfa-enable 123456

# 5. Create API key for your application
koneksi-auth create-key "My App Production"

# 6. Use the API credentials in your application
export KONEKSI_API_CLIENT_ID=ck_xxx
export KONEKSI_API_CLIENT_SECRET=cs_xxx

# Your application can now authenticate with Koneksi services

Next Steps

After setting up authentication:

Use your API keys with other Koneksi services
Integrate with koneksi-backup for data backup
Set up automated workflows with your CI/CD pipeline
Monitor API key usage through the Koneksi dashboard

Additional Resources

GitHub Repository: https://github.com/koneksi-tech/auth-cli
Issue Tracker: https://github.com/koneksi-tech/auth-cli/issues
Releases: https://github.com/koneksi-tech/auth-cli/releases

PreviousCommand-line Tools NextBackup and Restore CLI

Last updated 28 days ago

Complete How-To Guide

Features

Prerequisites

Installation

Option 1: Download Pre-built Binary

Option 2: Install from Source

Option 3: Using Go Install

Getting Started

Basic Command Structure

Global Flags

View Available Commands

User Registration

Step 1: Create a New Account

Example Output

Account Verification

Step 1: Login to Get Access Token

Step 2: Verify Your Account

Example Output

Login and Authentication

Standard Login

Save Tokens to Config

Login Output (Without MFA)

Multi-Factor Authentication (MFA)

Setting Up MFA

Login with MFA

Disabling MFA

API Key Management

Create an API Key

List Your API Keys

Revoke an API Key

Configuration

Configuration File

Environment Variables

Priority Order

Advanced Usage

Using Different Environments

JSON Output for Scripting

Refresh Expired Tokens

Check Current User

Troubleshooting

Common Issues

Debug Mode

Getting Help

Security Best Practices

Complete Workflow Example

Next Steps

Additional Resources