gtp4free/docs/authentication.md

# G4F - Authentication Guide
This documentation explains how to authenticate with G4F providers and configure GUI security. It covers API key management, cookie-based authentication, rate limiting, and GUI access controls.

---

Table of Contents

1. Provider Authentication
   
   • Prerequisites
     
   • API Key Setup
     
   • Synchronous Usage
     
   • Asynchronous Usage
     
   • Multiple Providers
     
   • Cookie-Based Authentication
     
   • Rate Limiting
     
   • Error Handling
     
   • Supported Providers
     
2. GUI Authentication
   
   • Server Setup
     
   • Browser Access
     
   • Programmatic Access
     
3. Best Practices
   
4. Troubleshooting
   

---

Provider Authentication

Prerequisites

• Python 3.7+
  
• Installed g4f package:
  bash pip install g4f
  
• API keys or cookies from providers (if required).
  

---

API Key Setup

Step 1: Set Environment Variables

For Linux/macOS (Terminal):

# Example for Anthropic
export ANTHROPIC_API_KEY="your_key_here"

# Example for HuggingFace
export HUGGINGFACE_API_KEY="another_key_here"

For Windows (Command Prompt):

:: Example for Anthropic
set ANTHROPIC_API_KEY=your_key_here

:: Example for HuggingFace
set HUGGINGFACE_API_KEY=another_key_here

For Windows (PowerShell):

# Example for Anthropic
$env:ANTHROPIC_API_KEY = "your_key_here"

# Example for HuggingFace
$env:HUGGINGFACE_API_KEY = "another_key_here"

Step 2: Initialize Client

from g4f.client import Client

# Example for Anthropic
client = Client(
    provider="g4f.Provider.Anthropic",
    api_key="your_key_here"  # Or use os.getenv("ANTHROPIC_API_KEY")
)

---

Synchronous Usage

from g4f.client import Client

# Initialize with Anthropic
client = Client(provider="g4f.Provider.Anthropic", api_key="your_key_here")

# Simple request
response = client.chat.completions.create(
    model="claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

---

Asynchronous Usage

import asyncio
from g4f.client import AsyncClient

async def main():
    # Initialize with Groq
    client = AsyncClient(provider="g4f.Provider.Groq", api_key="your_key_here")
    
    response = await client.chat.completions.create(
        model="mixtral-8x7b",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

---

Multiple Providers with API Keys

import os
from g4f.client import Client

# Using environment variables
providers = {
    "Anthropic": os.getenv("ANTHROPIC_API_KEY"),
    "Groq": os.getenv("GROQ_API_KEY")
}

for provider_name, api_key in providers.items():
    client = Client(provider=f"g4f.Provider.{provider_name}", api_key=api_key)
    response = client.chat.completions.create(
        model="claude-3.5-sonnet",
        messages=[{"role": "user", "content": f"Hello from {provider_name}!"}]
    )
    print(f"{provider_name}: {response.choices[0].message.content}")

---

Cookie-Based Authentication

For Providers Like Gemini/Bing:

1. Open your browser and log in to the provider's website.
   
2. Use developer tools (F12) to copy cookies:
   
   • Chrome/Edge: Application → Cookies
     
   • Firefox: Storage → Cookies
     

from g4f.Provider import Gemini

# Initialize with cookies
client = Client(
    provider=Gemini,
    cookies={
        "__Secure-1PSID": "your_cookie_value_here",
        "__Secure-1PSIDTS": "timestamp_value_here"
    }
)

---

Rate Limiting

from aiolimiter import AsyncLimiter

# Limit to 5 requests per second
rate_limiter = AsyncLimiter(max_rate=5, time_period=1)

async def make_request():
    async with rate_limiter:
        return await client.chat.completions.create(...)

---

Error Handling

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def safe_request():
    try:
        return client.chat.completions.create(...)
    except Exception as e:
        print(f"Attempt failed: {str(e)}")
        raise

---

Supported Providers

| Provider | Auth Type | Example Models |
|----------------|-----------------|----------------------|
| Anthropic | API Key | claude-3.5-sonnet |
| Gemini | Cookies | gemini-1.5-pro |
| Groq | API Key | mixtral-8x7b |
| HuggingFace | API Key | llama-3.1-70b |

Full list: Providers and Models

---

GUI Authentication

Server Setup

1. Create a password:
   ```bash

   Linux/macOS

   export G4F_API_KEY="your_password_here"

# Windows (Command Prompt) set G4F_API_KEY=your_password_here

# Windows (PowerShell) $env:G4F_API_KEY = "your_password_here"

2. Start the server:  
   ```bash
   python -m g4f --debug --port 8080 --g4f-api-key $G4F_API_KEY

---

Browser Access

1. Navigate to http://localhost:8080/chat/.
   
2. Use credentials:
   
   • Username: Any value (e.g., admin).
     
   • Password: Your G4F_API_KEY.
     

---

Programmatic Access

import requests

response = requests.get(
    "http://localhost:8080/chat/",
    auth=("admin", "your_password_here")
)
print("Success!" if response.status_code == 200 else f"Failed: {response.status_code}")

---

Best Practices

1. 🔒 Never hardcode keys
   
   • Use .env files or secret managers like AWS Secrets Manager.
     
2. 🔄 Rotate keys every 90 days
   
   • Especially critical for production environments.
     
3. 📊 Monitor API usage
   
   • Use tools like Prometheus/Grafana for tracking.
     
4. ♻️ Retry transient errors
   
   • Use the tenacity library for robust retry logic.
     

---

Troubleshooting

| Issue | Solution |
|---------------------------|-------------------------------------------|
| "Invalid API Key" | 1. Verify key spelling
2. Regenerate key in provider dashboard |
| "Cookie Expired" | 1. Re-login to provider website
2. Update cookie values |
| "Rate Limit Exceeded" | 1. Implement rate limiting
2. Upgrade provider plan |
| "Provider Not Found" | 1. Check provider name spelling
2. Verify provider compatibility |

---

⬆ Back to Top | Providers and Models →