# Authentication & Security

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:

```bash
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:

```bash
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

```bash
zw auth status
```

Output shows:

```
✓ Authenticated
Token: zw_...
```

If not authenticated:

```
✗ Not authenticated
```

## Logging Out

Clear your stored token:

```bash
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**

   ```bash
   # Add to .gitignore
   echo "~/.config/zw/" >> ~/.gitignore
   ```
2. **Use environment variables in scripts**

   ```bash
   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:

```yaml
# 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:

```bash
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:

```bash
# 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:

```yaml
# ~/.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](https://docs.zipwire.io/tools-and-integrations/configuration).