# 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

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

```bash
zw auth signup --name "Your Full Name" --whatsapp "+1234567890"
```

Replace the phone number with your WhatsApp number in [E.164 format](https://en.wikipedia.org/wiki/E.164) (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:

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

```bash
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 "+1234567890"
  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:

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

```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](/tools-and-integrations/configuration.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zipwire.io/tools-and-integrations/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.