Token Management API

API tokens are used to authenticate requests to the Zipf AI API. Tokens use Bearer authentication and can be scoped with specific permissions.

Security Best Practices

• Never commit tokens to version control
• Rotate tokens regularly (recommended: every 90 days)
• Use different tokens per environment (development, staging, production)
• Revoke unused tokens immediately
• Store tokens securely (environment variables, secrets manager)
• Monitor token usage via the dashboard

GET /api/v1/tokens

List all API tokens for your account with usage statistics.

Response:

{
  "tokens": [
    {
      "id": "uuid",
      "token_name": "Production API Token",
      "token_prefix": "wvr_abc1",
      "permissions": ["search", "crawl", "sessions"],
      "rate_limit_per_hour": 1000,
      "rate_limit_per_day": 10000,
      "is_active": true,
      "last_used_at": "2024-11-19T10:00:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "expires_at": null
    }
  ]
}

POST /api/v1/tokens

Create a new API token.

Parameters:

• token_name (required): Descriptive name for the token (max 255 chars)
• permissions (optional): Array of permission scopes (default: all permissions)
  • Available scopes: search, crawl, sessions, workflow

Response:

{
  "token": "wvr_abc123def456...",
  "token_id": "uuid",
  "token_name": "Production API Token",
  "token_prefix": "wvr_abc1",
  "permissions": ["search", "crawl"],
  "created_at": "2024-11-19T10:00:00Z",
  "message": "Token created successfully. Save this token - it won't be shown again!"
}

Important: The full token is only shown once during creation. Store it securely immediately.

Example

curl -X POST https://www.zipf.ai/api/v1/tokens \
  -H "Authorization: Bearer wvr_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token_name": "Production API",
    "permissions": ["search", "crawl", "sessions"]
  }'

PATCH /api/v1/tokens/{id}

Update an existing token's name or permissions.

Parameters:

• name (optional): Update token display name
• permissions (optional): Update scoped permissions object
  • search (Boolean) - Allow search operations
  • crawl (Boolean) - Allow crawl operations

Response:

{
  "token": {
    "id": "uuid",
    "name": "Updated Token Name",
    "token_prefix": "wvr_abc1",
    "permissions": {
      "search": true,
      "crawl": false
    },
    "is_active": true,
    "updated_at": "2024-11-19T12:30:00Z"
  },
  "message": "Token updated successfully"
}

Use Cases:

• Rename tokens for better organization
• Restrict permissions (e.g., disable crawl access)
• Update token scope without creating new token

Example

# Restrict to search-only access
curl -X PATCH https://www.zipf.ai/api/v1/tokens/TOKEN_ID \
  -H "Authorization: Bearer wvr_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search-Only Token",
    "permissions": {
      "search": true,
      "crawl": false
    }
  }'

GET /api/v1/tokens/{id}/logs

Get usage logs for a specific token (last 100 requests).

Response:

{
  "logs": [
    {
      "id": "uuid",
      "endpoint": "/api/v1/search",
      "method": "POST",
      "status_code": 200,
      "response_time_ms": 1234,
      "credits_used": 5,
      "created_at": "2024-11-19T12:00:00Z",
      "ip_address": "203.0.113.42",
      "user_agent": "MyApp/1.0",
      "request_metadata": {
        "query": "AI infrastructure startups"
      }
    }
  ]
}

Fields:

• endpoint: API route called
• method: HTTP method (GET, POST, etc.)
• status_code: Response status code
• response_time_ms: Request duration in milliseconds
• credits_used: Credits consumed by this request
• request_metadata: Additional request context (query, filters, etc.)

Use Cases:

• Monitor API usage patterns
• Debug integration issues
• Track credit consumption per token
• Audit token activity

Limits:

• Returns last 100 requests only
• Excludes request_body and response_data for performance
• Sorted by most recent first

Example

curl https://www.zipf.ai/api/v1/tokens/TOKEN_ID/logs \
  -H "Authorization: Bearer wvr_TOKEN"

DELETE /api/v1/tokens/{id}

Revoke an API token (soft delete). Sets is_active: false while preserving audit trail.

Requirements:

• User must own the token
• Cannot revoke the token being used for authentication

Response:

{
  "message": "Token revoked successfully",
  "token_id": "uuid",
  "revoked_at": "2024-11-19T10:00:00Z"
}

Example

curl -X DELETE https://www.zipf.ai/api/v1/tokens/TOKEN_ID \
  -H "Authorization: Bearer wvr_ACTIVE_TOKEN"

Token Permissions

Tokens can be scoped to specific operations:

Default: If no permissions are specified, token has access to all operations.

Rate Limits

Rate limits are enforced per token and per customer:

Rate limit headers are included in all API responses:

• X-RateLimit-Limit - Maximum requests allowed
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Unix timestamp when limit resets

Token Lifecycle

1. Creation - Generate via dashboard (/dashboard/tokens) or API
2. Active Use - Authenticate API requests
3. Monitoring - Track usage in dashboard
4. Rotation - Create new token, update applications, revoke old token
5. Revocation - Soft delete when no longer needed

Best Practices

Environment Management

# Development
export ZIPF_API_KEY="wvr_dev_token..."

# Production
export ZIPF_API_KEY="wvr_prod_token..."

Token Rotation Script

# 1. Create new token
NEW_TOKEN=$(curl -X POST https://www.zipf.ai/api/v1/tokens \
  -H "Authorization: Bearer $OLD_TOKEN" \
  -d '{"token_name": "Rotated Production Token"}' | jq -r '.token')

# 2. Update environment variables
export ZIPF_API_KEY="$NEW_TOKEN"

# 3. Verify new token works
curl https://www.zipf.ai/api/v1 -H "Authorization: Bearer $NEW_TOKEN"

# 4. Revoke old token
curl -X DELETE https://www.zipf.ai/api/v1/tokens/$OLD_TOKEN_ID \
  -H "Authorization: Bearer $NEW_TOKEN"

Usage Monitoring

Check token usage regularly via the dashboard:

• View requests per hour/day
• Monitor credit consumption per token
• Identify unused tokens for revocation
• Track last used timestamp

Troubleshooting

401 Unauthorized

• Token is invalid or revoked
• Token prefix doesn't match active token
• Token not provided in Authorization header

403 Forbidden

• Token lacks required permissions for operation
• Token is valid but operation is restricted

429 Rate Limit Exceeded

• Too many requests in current time window
• Check X-RateLimit-Reset header for reset time
• Implement exponential backoff

See Also

• Authentication - How to use tokens in requests
• Rate Limits - Detailed rate limiting information
• Credits System - Credit consumption per operation