cannaiq/backend/API_TOKENS_GUIDE.md

# API Token Management System

## Overview

Complete API token management with usage tracking, rate limiting, and analytics.

## Features

✅ **Create Named API Tokens** - Give each token a descriptive name (e.g., "WordPress Plugin - Main Site")
✅ **Usage Tracking** - Track every API request (endpoint, response time, size, IP, user agent)
✅ **Rate Limiting** - Configurable per-token rate limits
✅ **Analytics** - View usage stats, popular endpoints, response times
✅ **Endpoint Restrictions** - Limit tokens to specific endpoints
✅ **Expiration Dates** - Set token expiry dates
✅ **Enable/Disable** - Activate or deactivate tokens without deleting
✅ **Security** - Tokens are hashed, one-way generation

## Creating an API Token

### Via API

**Endpoint:** `POST /api/api-tokens`

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WordPress Plugin - Main Site",
    "description": "Token for the main WordPress website",
    "rate_limit": 200,
    "expires_at": "2026-12-31",
    "allowed_endpoints": ["/products*", "/stores*", "/categories*"]
  }' \
  http://localhost:3010/api/api-tokens
```

**Response:**
```json
{
  "token": {
    "id": 1,
    "name": "WordPress Plugin - Main Site",
    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "description": "Token for the main WordPress website",
    "active": true,
    "rate_limit": 200,
    "allowed_endpoints": ["/products*", "/stores*", "/categories*"],
    "expires_at": "2026-12-31T00:00:00.000Z",
    "created_at": "2025-01-15T10:30:00.000Z"
  },
  "message": "API token created successfully. Save this token securely - it cannot be retrieved later."
}
```

**IMPORTANT:** Save the token immediately! It cannot be retrieved after creation.

## Using an API Token

Replace JWT token with API token in Authorization header:

```bash
curl -H "Authorization: Bearer a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
  http://localhost:3010/api/products?store_id=1
```

The API will:
1. ✅ Validate the token
2. ✅ Check if it's active
3. ✅ Check if it's expired
4. ✅ Verify endpoint is allowed
5. ✅ Check rate limit
6. ✅ Track the request
7. ✅ Return data with rate limit headers

## Token Configuration

### Rate Limiting

Set requests per minute for each token:

```json
{
  "name": "Mobile App",
  "rate_limit": 500
}
```

**Rate Limit Headers** in responses:
```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 2025-01-15T10:31:00.000Z
```

When limit is exceeded:
```json
{
  "error": "Rate limit exceeded",
  "limit": 500,
  "current": 501,
  "retry_after": 60
}
```

### Endpoint Restrictions

Limit tokens to specific endpoints using wildcards:

```json
{
  "name": "Public Website",
  "allowed_endpoints": [
    "/products*",      // All product endpoints
    "/stores*",        // All store endpoints
    "/categories*"     // All category endpoints
  ]
}
```

Examples:
- `/products*` - matches `/products`, `/products/123`, `/products/meta/brands`
- `/stores/*/brands` - matches `/stores/1/brands`, `/stores/2/brands`
- `null` or `[]` - allows all endpoints

### Expiration

Set token expiry date:

```json
{
  "name": "Temporary Integration",
  "expires_at": "2025-12-31"
}
```

After expiration:
```json
{
  "error": "Token has expired"
}
```

## Managing Tokens

### List All Tokens

```bash
GET /api/api-tokens
```

Returns tokens with usage stats:
```json
{
  "tokens": [
    {
      "id": 1,
      "name": "WordPress Plugin - Main Site",
      "description": "Token for the main WordPress website",
      "active": true,
      "rate_limit": 200,
      "last_used_at": "2025-01-15T12:45:00.000Z",
      "created_at": "2025-01-15T10:30:00.000Z",
      "requests_24h": 1247,
      "requests_7d": 8932,
      "total_requests": 45123
    }
  ]
}
```

### Get Single Token

```bash
GET /api/api-tokens/:id
```

### Update Token

```bash
PUT /api/api-tokens/:id
```

Update token properties:
```json
{
  "name": "WordPress Plugin - Main Site (Updated)",
  "active": false,
  "rate_limit": 300
}
```

### Delete Token

```bash
DELETE /api/api-tokens/:id
```

## Usage Analytics

### Token-Specific Usage

**Endpoint:** `GET /api/api-tokens/:id/usage?days=7`

```json
{
  "hourly_usage": [
    {
      "hour": "2025-01-15T12:00:00.000Z",
      "requests": 245,
      "avg_response_time": 127,
      "successful_requests": 243,
      "failed_requests": 2
    }
  ],
  "endpoint_usage": [
    {
      "endpoint": "/products",
      "method": "GET",
      "requests": 1840,
      "avg_response_time": 132
    },
    {
      "endpoint": "/stores",
      "method": "GET",
      "requests": 423,
      "avg_response_time": 89
    }
  ],
  "recent_requests": [
    {
      "endpoint": "/products",
      "method": "GET",
      "status_code": 200,
      "response_time_ms": 145,
      "ip_address": "192.168.1.100",
      "created_at": "2025-01-15T12:45:30.000Z"
    }
  ]
}
```

### Overall API Statistics

**Endpoint:** `GET /api/api-tokens/stats/overview?days=7`

```json
{
  "overview": {
    "active_tokens": 5,
    "total_requests": 45892,
    "avg_response_time": 142,
    "successful_requests": 45234,
    "failed_requests": 658
  },
  "top_tokens": [
    {
      "id": 1,
      "name": "WordPress Plugin - Main Site",
      "requests": 18234,
      "avg_response_time": 134
    }
  ],
  "top_endpoints": [
    {
      "endpoint": "/products",
      "method": "GET",
      "requests": 28934,
      "avg_response_time": 145
    }
  ]
}
```

## Usage Tracking

Every API request tracks:

- ✅ **Token ID** - Which token made the request
- ✅ **Endpoint** - Which API endpoint was called
- ✅ **Method** - GET, POST, PUT, DELETE
- ✅ **Status Code** - 200, 404, 500, etc.
- ✅ **Response Time** - Milliseconds
- ✅ **Request Size** - Bytes
- ✅ **Response Size** - Bytes
- ✅ **IP Address** - Client IP
- ✅ **User Agent** - Client identifier
- ✅ **Timestamp** - When request was made

This data powers:
- Usage analytics dashboards
- Performance monitoring
- Rate limiting
- Billing/quota tracking
- Security auditing

## Use Cases

### WordPress Plugin Token
```json
{
  "name": "WordPress - example.com",
  "description": "Main WordPress website integration",
  "rate_limit": 200,
  "allowed_endpoints": ["/products*", "/stores*", "/categories*"]
}
```

### Mobile App Token
```json
{
  "name": "iOS App - Production",
  "description": "Production iOS application",
  "rate_limit": 500,
  "allowed_endpoints": null
}
```

### Partner Integration Token
```json
{
  "name": "Partner ABC - Integration",
  "description": "Third-party partner integration",
  "rate_limit": 100,
  "allowed_endpoints": ["/products*"],
  "expires_at": "2025-12-31"
}
```

### Testing/Development Token
```json
{
  "name": "Development - Local Testing",
  "description": "For local development and testing",
  "rate_limit": 1000,
  "expires_at": "2025-06-30"
}
```

## Security Best Practices

1. **Name Tokens Descriptively** - Know where requests come from
2. **Use Minimum Rate Limits** - Start low, increase if needed
3. **Restrict Endpoints** - Only allow necessary endpoints
4. **Set Expiration Dates** - Especially for temporary integrations
5. **Monitor Usage** - Watch for unusual patterns
6. **Rotate Tokens** - Periodically create new tokens
7. **Disable Before Deleting** - Test impact before removal
8. **Store Securely** - Treat like passwords
9. **Use HTTPS** - Always use secure connections
10. **Track IP Addresses** - Monitor for unauthorized access

## Database Schema

### api_tokens Table
```sql
CREATE TABLE api_tokens (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    token VARCHAR(255) UNIQUE NOT NULL,
    description TEXT,
    user_id INTEGER REFERENCES users(id),
    active BOOLEAN DEFAULT true,
    rate_limit INTEGER DEFAULT 100,
    allowed_endpoints TEXT[],
    expires_at TIMESTAMP,
    last_used_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### api_token_usage Table
```sql
CREATE TABLE api_token_usage (
    id SERIAL PRIMARY KEY,
    token_id INTEGER REFERENCES api_tokens(id) ON DELETE CASCADE,
    endpoint VARCHAR(255) NOT NULL,
    method VARCHAR(10) NOT NULL,
    status_code INTEGER,
    response_time_ms INTEGER,
    request_size INTEGER,
    response_size INTEGER,
    ip_address INET,
    user_agent TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## Admin UI

Access token management at:
```
http://localhost:5173/api-tokens
```

Features:
- ✅ Create new tokens
- ✅ View all tokens with usage stats
- ✅ Enable/disable tokens
- ✅ View detailed usage analytics
- ✅ Monitor rate limits
- ✅ Delete tokens

## Monitoring & Alerts

Set up monitoring for:

1. **Rate Limit Violations** - Track 429 responses
2. **Failed Requests** - Monitor 4xx/5xx errors
3. **Unusual Patterns** - Spike in requests
4. **Token Expiration** - Alert before expiry
5. **Slow Responses** - Performance degradation

## Migration from JWT to API Tokens

If currently using JWT tokens:

1. Create API token for each integration
2. Update clients to use new API tokens
3. Monitor usage to ensure migration is successful
4. Deactivate old JWT tokens
5. Clean up old authentication

API tokens are better for:
- ✅ Non-user integrations (plugins, apps, partners)
- ✅ Usage tracking
- ✅ Per-client rate limiting
- ✅ Endpoint restrictions

Keep JWT for:
- ✅ User authentication
- ✅ Admin panel access
- ✅ Short-lived sessions