Authentication & Security

Authentication and token management for the Zipwire CLI

The Zipwire CLI uses API tokens for authentication. This guide covers how to authenticate, manage tokens securely, and troubleshoot auth issues.

Authentication Methods

Sign Up for a New Account (Recommended for New Users)

If you don't have a Zipwire account yet, create one directly from the CLI:

zw auth signup --name "Your Full Name" --whatsapp "[phone]"

Replace the phone number with your WhatsApp number in E.164 format (e.g., +1 for US, +44 for UK).

What happens:

1. Your API token is automatically generated and saved to ~/.config/zw/config.yaml

2. A WhatsApp message from Zipwire's bot arrives with onboarding instructions

3. Follow the bot's prompts to complete your account activation

Once you receive the bot's welcome confirmation in WhatsApp, you're all set. Return to the CLI and start using it immediately—your token is already in place and ready to go. No additional setup needed.

Browser-Based Login (For Existing Users)

If you already have a Zipwire account, login via your browser:

zw auth login

This will:

1. Open your default browser automatically

2. Redirect you to Zipwire's login page

3. Ask you to sign in with your passkey or wallet

4. Generate an API token

5. Save it automatically to ~/.config/zw/config.yaml

Manual Token Entry

If you already have an API token, set it directly:

zw auth set-token your-api-token

To get an API token:

1. Log into Zipwire web app

2. Go to Account Settings

3. Find the API Tokens section

4. Generate or copy your token

Checking Your Authentication Status

zw auth status

If authenticated, you'll see:

↓ Authentication status
  Authenticated
  Token: zw_...

If not authenticated:

↓ Authentication status
  Not authenticated
  Recommended if you don't have an account yet:
    zw auth signup --name "Your Name" --whatsapp "[phone]"
  Only if you already have an account:
    zw auth login

Accessing Zipwire on the Web

Generate a magic login link to access Zipwire's website without needing to log in again:

zw auth login-link

This creates a temporary magic link that you can use in your browser for direct website access. No need to re-authenticate.

Logging Out

Clear your stored token:

zw auth logout

This removes the token from your config file. You'll need to authenticate again before using the CLI.

Token Management

Where Your Token is Stored

Your token is stored in:

~/.config/zw/config.yaml

Important: This file contains sensitive information. Protect it like you would a password or private key.

Security Best Practices

1. Never commit tokens to version control

   # Add to .gitignore
   echo "~/.config/zw/" >> ~/.gitignore

2. Use environment variables in scripts

   export ZW_API_TOKEN="your-token"
   zw auth login --token $ZW_API_TOKEN

3. Rotate tokens regularly

   • Generate a new token

   • Update your config

   • Delete the old token from the web app

4. Use different tokens for different contexts

   • One token for your local development

   • A different token for CI/CD pipelines

   • Separate tokens for different machines if needed

Using Tokens in CI/CD

For automated workflows (GitHub Actions, GitLab CI, etc.), use environment variables:

# GitHub Actions example
jobs:
  track-time:
    runs-on: ubuntu-latest
    steps:
      - run: zw auth login --token ${{ secrets.ZW_API_TOKEN }}
      - run: zw journal track "CI/CD job" -d 1h

Troubleshooting Authentication

"Invalid API Key" Error

Verify your token:

1. Check the token in your config: cat ~/.config/zw/config.yaml

2. Ensure it hasn't expired

3. Generate a new token in the web app if needed

4. Update with: zw auth login --token <new-token>

"Not Authenticated" Error

You need to authenticate first:

zw auth login

Token Accidentally Leaked

If you accidentally expose your token (e.g., in a commit):

1. Delete the token immediately from your config

2. Revoke it in the web app (Account Settings > API Tokens)

3. Generate a new token

4. Update your config with the new token

Multiple Machines

Each machine needs its own authentication. Authenticate on each machine separately:

# On machine 1
zw auth login

# On machine 2
zw auth login

You can use the same API token on multiple machines, or create separate tokens for isolation.

Config File Format

The CLI stores configuration in YAML format:

# ~/.config/zw/config.yaml
api-base-url: https://api.zipwire.io
api-token: zw_your_token_here_...
output-format: human
no-color: false

You can edit this file directly if needed, but it's safer to use zw auth login or zw config commands.

---

For more configuration options, see the Configuration guide.