foxhunt/testing/integration/e2e_helpers/QUICKSTART.md

# JWT Token Generator - Quick Start

**5-Minute Guide** for E2E Testing

## Installation

✅ **Already installed** - No additional setup required!

Dependencies: Python3 + PyJWT (already available)

## Basic Usage

### 1. Generate Token (Default)
```bash
cd tests/e2e_helpers
./jwt_token_generator.sh
```
Output: JWT token for trader with 1-hour expiration

### 2. Use in API Request
```bash
TOKEN=$(./jwt_token_generator.sh)
curl -H "Authorization: Bearer $TOKEN" http://localhost:50051/api/v1/orders
```

### 3. Admin Token
```bash
./jwt_token_generator.sh admin_user admin "api.access,system.admin"
```

### 4. Custom Expiration (10 minutes)
```bash
./jwt_token_generator.sh test_user trader "api.access" 600
```

## Common Patterns

### E2E Test Script
```bash
#!/bin/bash
cd tests/e2e_helpers

# Generate token
TOKEN=$(./jwt_token_generator.sh)

# Test endpoint
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:50051/api/v1/orders

# Submit order
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC/USD", "quantity": 1.0, "side": "buy"}' \
  http://localhost:50051/api/v1/orders
```

### Load Test
```bash
# Generate 10 tokens
for i in {1..10}; do
    TOKEN=$(./jwt_token_generator.sh "user_$i" trader "api.access")
    echo "$TOKEN" > "token_$i.txt"
done
```

## Command Syntax

```bash
./jwt_token_generator.sh [user_id] [role] [permissions] [ttl_seconds]
```

| Argument | Default | Example |
|----------|---------|---------|
| user_id | test_user_123 | admin_user |
| role | trader | admin, viewer |
| permissions | api.access | "api.access,system.admin" |
| ttl_seconds | 3600 | 600 (10 min) |

## Role Presets

```bash
# Trader (default)
./jwt_token_generator.sh

# Admin
./jwt_token_generator.sh admin_user admin "api.access,system.admin"

# Viewer (read-only)
./jwt_token_generator.sh viewer_user viewer "api.read"
```

## Environment Variable

```bash
# Custom JWT secret
export JWT_SECRET="your-secret-key-here"
./jwt_token_generator.sh
```

## Troubleshooting

### Token not working?
1. Check API Gateway is running: `curl http://localhost:8080/health`
2. Verify JWT secret matches: Check `.env` file
3. Regenerate token: `TOKEN=$(./jwt_token_generator.sh)`

### Permission denied?
Generate admin token:
```bash
./jwt_token_generator.sh admin admin "api.access,system.admin"
```

### Token expired?
Use shorter expiration for testing:
```bash
./jwt_token_generator.sh user trader "api.access" 60  # 60 seconds
```

## Documentation

- **Full docs**: [README.md](README.md)
- **Examples**: [USAGE_EXAMPLES.md](USAGE_EXAMPLES.md)
- **Validation**: [VALIDATION_REPORT.md](VALIDATION_REPORT.md)

## Quick Reference

```bash
# Default token (trader, 1 hour)
./jwt_token_generator.sh

# Admin token
./jwt_token_generator.sh admin_user admin "api.access,system.admin"

# Short-lived (60 sec)
./jwt_token_generator.sh user trader "api.access" 60

# Multiple permissions
./jwt_token_generator.sh user trader "api.access,orders.submit,risk.view"

# Custom secret
JWT_SECRET="secret" ./jwt_token_generator.sh

# Inspect token
TOKEN=$(./jwt_token_generator.sh)
python3 -c "import jwt, json; token='$TOKEN'; print(json.dumps(jwt.decode(token, options={'verify_signature': False}), indent=2))"
```

---

**Ready to use!** Run `./jwt_token_generator.sh` to get started.