From e61cd171616b5896be0b18b283871a5500b8cc7a Mon Sep 17 00:00:00 2001
From: nulllabtests <creatorplntu@proton.me>
Date: Sat, 1 Mar 2025 20:10:10 -0500
Subject: [PATCH] docs: Add API Key authentication documentation

- Add comprehensive guide for API Key authentication
- Include complete example with database integration
- Add security considerations and best practices
- Update security index to reference new guide

Fixes #142
---
 docs/en/docs/tutorial/security/api-key.md | 152 ++++++++++++++++++++++
 docs/en/docs/tutorial/security/index.md   |   5 +-
 2 files changed, 156 insertions(+), 1 deletion(-)
 create mode 100644 docs/en/docs/tutorial/security/api-key.md

diff --git a/docs/en/docs/tutorial/security/api-key.md b/docs/en/docs/tutorial/security/api-key.md
new file mode 100644
index 000000000..fd235b263
--- /dev/null
+++ b/docs/en/docs/tutorial/security/api-key.md
@@ -0,0 +1,152 @@
+# API Key Authentication
+
+API Key authentication is a simple and common way to authenticate API requests. In this approach, clients include a special key in their request headers to prove their identity.
+
+## Import Dependencies
+
+First, import the required FastAPI components:
+
+```python
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.security import APIKeyHeader
+from starlette import status
+```
+
+## Create the API Key Header
+
+Define the header that will contain the API key. By convention, API key headers often start with `X-`:
+
+```python
+API_KEY_HEADER = APIKeyHeader(name="X-API-Key")
+```
+
+## Create the Authentication Function
+
+Create a function that will validate the API key and return the authenticated user's data:
+
+```python
+def verify_api_key(api_key: str = Depends(API_KEY_HEADER)):
+    """Verify the API key and return user data."""
+    # In a real application, you would verify the API key against a database
+    if api_key == "your-secure-api-key":
+        return {
+            "user_id": 123,
+            "permissions": ["read", "write"]
+        }
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid API Key",
+        headers={"WWW-Authenticate": "ApiKey"},
+    )
+```
+
+## Use the Authentication in Your Routes
+
+Apply the authentication to your routes using FastAPI's dependency injection:
+
+```python
+app = FastAPI()
+
+@app.get("/secure-endpoint/")
+def secure_endpoint(user_data: dict = Depends(verify_api_key)):
+    return {
+        "message": "You have access!",
+        "user_data": user_data
+    }
+```
+
+## Making Authenticated Requests
+
+To access the protected endpoint, include the API key in your request headers:
+
+```bash
+curl -H "X-API-Key: your-secure-api-key" http://localhost:8000/secure-endpoint/
+```
+
+## Complete Example
+
+Here's a complete example that includes database integration:
+
+```python
+from fastapi import Depends, FastAPI, HTTPException
+from fastapi.security import APIKeyHeader
+from starlette import status
+from typing import Optional
+from pydantic import BaseModel
+
+# Models
+class User(BaseModel):
+    id: int
+    username: str
+    permissions: list[str]
+
+# Setup
+app = FastAPI()
+API_KEY_HEADER = APIKeyHeader(name="X-API-Key")
+
+# Simulated database (replace with your actual database logic)
+api_keys_db = {
+    "your-secure-api-key": User(
+        id=123,
+        username="admin",
+        permissions=["read", "write"]
+    )
+}
+
+def get_user_from_api_key(api_key: str) -> Optional[User]:
+    """Get user data from database using API key."""
+    return api_keys_db.get(api_key)
+
+def verify_api_key(api_key: str = Depends(API_KEY_HEADER)) -> User:
+    """Verify API key and return user data."""
+    user = get_user_from_api_key(api_key)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid API Key",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+    return user
+
+@app.get("/secure-endpoint/")
+def secure_endpoint(user: User = Depends(verify_api_key)):
+    return {
+        "message": "You have access!",
+        "user": user
+    }
+
+@app.get("/admin-endpoint/")
+def admin_endpoint(user: User = Depends(verify_api_key)):
+    if "write" not in user.permissions:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Insufficient permissions"
+        )
+    return {
+        "message": "You have admin access!",
+        "user": user
+    }
+```
+
+## Security Considerations
+
+When implementing API key authentication:
+
+1. Always use HTTPS in production to prevent key interception
+2. Store API keys securely (hashed in the database)
+3. Implement rate limiting to prevent abuse
+4. Consider key expiration and rotation policies
+5. Log authentication failures for security monitoring
+
+## Alternative Header Names
+
+While this example uses `X-API-Key`, you can use any header name that fits your needs:
+
+```python
+# Common alternatives
+API_KEY_HEADER = APIKeyHeader(name="Authorization")  # Using "Bearer <api-key>"
+API_KEY_HEADER = APIKeyHeader(name="Api-Key")
+API_KEY_HEADER = APIKeyHeader(name="X-Auth-Token")
+```
+
+Just ensure you document the expected header name for your API consumers.
diff --git a/docs/en/docs/tutorial/security/index.md b/docs/en/docs/tutorial/security/index.md
index d33a2b14d..c6e6a30e1 100644
--- a/docs/en/docs/tutorial/security/index.md
+++ b/docs/en/docs/tutorial/security/index.md
@@ -12,7 +12,10 @@ But first, let's check some small concepts.
 
 ## In a hurry?
 
-If you don't care about any of these terms and you just need to add security with authentication based on username and password *right now*, skip to the next chapters.
+If you need quick security solutions:
+
+* For simple API key authentication, check the [API Key Authentication](api-key.md) guide
+* For username/password authentication, continue to the next chapters
 
 ## OAuth2