Skip to content

Authentication

The WhookTown CLI uses token-based authentication. You can log in interactively or use tokens for automation.

Interactive Login

wt login

Flow:

  1. Enter your email address when prompted
  2. Check your email inbox
  3. Click the validation link
  4. CLI automatically saves the token

The token is stored in ~/.whooktown/config.yaml.

Verify Login

wt whoami

Output: 

Email: your@email.com
Account ID: abc123...
Token Type: user
Context: default
Environment: PROD

Logout

wt logout

Removes the stored token from the config file.

Token Authentication

For automation and scripts, use tokens directly.

Using --token Flag

wt --token <your-token> workflow list

Environment Variable

export WT_TOKEN=<your-token>
wt workflow list

In Config File

The config file stores tokens per context:

contexts:
  default:
    token: "eyJhbGciOiJIUzI1NiIs..."

Token Management

List Tokens

wt token list

Output: 

NAME              TYPE      STATUS     TOKEN
My Script         sensor    valid      eyJh...xyz
Dashboard         viewer    valid      eyJh...abc
Expired Token     user      expired    eyJh...def

Create Token

wt token create --name "My Integration" --type sensor

Options:

Flag Description
--name Descriptive name for the token
--type Token type: user, sensor, or viewer

Output: 

Token created successfully!

Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

⚠️  Save this token now - it won't be shown again!

Save your token

The full token is only displayed once. Copy it immediately.

Token Types

Type Permissions Use Case
user Full user access General automation
sensor Sensor write only Monitoring integrations
viewer Read-only access Dashboard displays

Revoke Token

wt token revoke <token>

The token is immediately invalidated. Any systems using it will lose access.

Multi-Environment Contexts

Manage multiple environments (dev, staging, prod) with contexts.

List Contexts

wt config get-contexts

Output: 

CONTEXT   ENVIRONMENT   CURRENT
default   PROD          *
dev       DEV
staging   PROD

Switch Context

wt config use-context dev

All subsequent commands use the dev context's token and settings.

Context Configuration

Each context can have:

contexts:
  prod:
    name: prod
    token: "eyJ..."
    environment: PROD
    default_layout: "layout-uuid"

  dev:
    name: dev
    token: "eyJ..."
    environment: DEV
    # Custom URLs for self-hosted
    auth_url: "https://auth.dev.example.com"
    sensor_url: "https://sensor.dev.example.com"
    ui_url: "https://api.dev.example.com"

Per-Command Override

Use --env to override context for a single command:

# Check prod quota while in dev context
wt --env prod layout quota

Troubleshooting

"Not logged in"

wt login
# or
wt --token <token> <command>

"Invalid token"

  • Verify the token is copied correctly (full token, not truncated)
  • Check if the token has expired
  • Try creating a new token

"Connection error"

# Check config
wt config show

# Debug mode
wt --debug whoami

Token Not Found in Email

  • Check spam/junk folder
  • Verify email address is correct
  • Wait a few minutes and try again
  • Contact support if issues persist