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

Browser-Based Login (Recommended)

For interactive use, 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 login --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

Output shows:

✓ Authenticated
Token: zw_...

If not authenticated:

✗ Not authenticated

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.