diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx
index 2d280e9..7665070 100644
--- a/api-reference/authentication.mdx
+++ b/api-reference/authentication.mdx
@@ -1,243 +1,92 @@
---
title: "Authentication"
-description: "API authentication, key management, and security best practices"
+description: "How to authenticate Request Network API calls with API keys or Client ID"
---
-
-**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions).
-
-
-## Authentication Overview
-
-Request Network API uses API key authentication to secure access to endpoints. This guide covers how to obtain, manage, and use your API keys securely.
-
-## Getting API Keys
-
-
-
- Sign up for a Request Network account at the [Request Portal](https://portal.request.network)
-
-
- Navigate to the API Keys section and create a new API key for your project
-
-
- Store your API key securely in environment variables
-
-
- Make your first authenticated API call to verify setup
-
-
-
-## API Key Management
-
-
-
- **Production Environment:**
- - Use separate keys for production
- - Implement key rotation policies
- - Monitor usage and access logs
- - Set up rate limiting and alerts
-
-
-
- **Development Environment:**
- - Use testnet for development
- - Separate keys for each environment
- - Team access management
- - Testing and debugging tools
-
-
+## Overview
-## Authentication Methods
-
-
-
- **API Key in Header (Recommended):**
-
- ```bash
- curl -X POST https://api.request.network/v2/requests \
- -H "x-api-key: YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "currency": "USD",
- "expectedAmount": "100",
- "payeeIdentity": "0x...",
- "reason": "Test invoice"
- }'
- ```
-
-
- **Optional Headers:**
- - `x-client-id`: Your client identifier for request tracking
- - `Origin`: Required for browser-based requests (CORS)
-
-
-
-
- **Secure Key Storage:**
-
- ```javascript
- // .env file
- REQUEST_NETWORK_GATEWAY_URL=https://sepolia.gateway.request.network/
-
- // Application code
- import { RequestNetwork } from '@requestnetwork/request-client.js';
- import { EthereumPrivateKeySignatureProvider } from '@requestnetwork/epk-signature';
-
- const signatureProvider = new EthereumPrivateKeySignatureProvider({
- method: Types.SIGNATURE_METHOD.ECDSA,
- privateKey: process.env.PRIVATE_KEY
- });
-
- const requestNetwork = new RequestNetwork({
- nodeConnectionConfig: {
- baseURL: process.env.REQUEST_NETWORK_GATEWAY_URL
- },
- signatureProvider
- });
- ```
-
-
-
- **SDK Authentication:**
-
- ```javascript
- import { RequestNetwork, Types } from '@requestnetwork/request-client.js';
- import { EthereumPrivateKeySignatureProvider } from '@requestnetwork/epk-signature';
-
- const signatureProvider = new EthereumPrivateKeySignatureProvider({
- method: Types.SIGNATURE_METHOD.ECDSA,
- privateKey: process.env.PRIVATE_KEY
- });
-
- const requestNetwork = new RequestNetwork({
- nodeConnectionConfig: {
- baseURL: 'https://sepolia.gateway.request.network/'
- },
- signatureProvider
- });
- ```
-
-
-
-## Security Best Practices
-
-
-
- **Protect Your API Keys:**
- - Never commit API keys to version control
- - Use environment variables for key storage
- - Implement key rotation policies
- - Monitor for unauthorized usage
- - Use different keys for different environments
-
-
-
- **Secure Communication:**
- - Always use HTTPS for API calls
- - Implement request signing for sensitive operations
- - Use webhook signature verification
- - Implement rate limiting on your endpoints
-
-
-
- **Manage Access:**
- - Use principle of least privilege
- - Implement role-based access control
- - Regular access audits
- - Immediate revocation of compromised keys
-
-
-
-## Rate Limits
+Request Network API supports two authentication modes:
-
-**Rate Limiting Information**
+- `x-api-key` for server-side integrations
+- `x-client-id` for browser/client integrations (with `Origin` header)
-Current rate limits apply to API usage. Contact support for enterprise rate limit increases.
-
+Use this page as the canonical auth reference. For credential creation and webhook setup in the portal, see [API Portal: Manage API Keys and Webhooks](/request-network-api/api-portal-manage-api-keys-and-webhooks).
-
-
- **Default Rate Limits:**
- - 100 requests per minute
- - 1,000 requests per hour
- - 10,000 requests per day
-
- **Applies to:** Most API endpoints
-
-
-
- **Webhook Rate Limits:**
- - 50 webhook deliveries per minute
- - Exponential backoff for retries
- - Maximum 5 retry attempts
-
- **Applies to:** Webhook delivery endpoints
-
-
+## Choose the Right Method
-## Error Codes
+| Method | Best for | Header(s) |
+| --- | --- | --- |
+| API Key | Backend services, cron jobs, trusted server environments | `x-api-key` |
+| Client ID | Browser/front-end calls where client auth is required | `x-client-id` (+ `Origin`) |
-Common authentication error responses:
+## API Key Authentication
-
-```json 401 Unauthorized
-{
- "error": {
- "code": "UNAUTHORIZED",
- "message": "Invalid or missing API key",
- "details": "Please provide a valid API key in the Authorization header"
- }
-}
-```
+Use API keys for backend calls.
+
+### Example
-```json 403 Forbidden
-{
- "error": {
- "code": "FORBIDDEN",
- "message": "API key does not have required permissions",
- "details": "This operation requires additional permissions"
- }
-}
+```bash cURL
+curl -X GET 'https://api.request.network/v2/request/{requestId}' \
+ -H 'x-api-key: YOUR_API_KEY'
```
-```json 429 Rate Limited
-{
- "error": {
- "code": "RATE_LIMITED",
- "message": "Rate limit exceeded",
- "details": "Too many requests. Please try again later.",
- "retryAfter": 60
- }
-}
+## Client ID Authentication
+
+Use Client ID when your integration needs browser-side authentication flow.
+
+### Example
+
+```bash cURL
+curl -X GET 'https://api.request.network/v2/request/{requestId}' \
+ -H 'x-client-id: YOUR_CLIENT_ID' \
+ -H 'Origin: https://your-app.example'
```
-
-## What's Next?
+
+For browser-based requests, `Origin` is part of the request context and is required for Client ID auth.
+
+
+## Header Reference
+
+- `x-api-key`: API key used for server-side auth
+- `x-client-id`: Client identifier used for client-side auth
+- `Origin`: required with Client ID flows in browser contexts
+
+## Common Authentication Errors
+
+### 401 Unauthorized
+
+- Missing auth header
+- Invalid/expired API key or client ID
+
+### 403 Forbidden
+
+- Credentials are valid but not allowed for the requested operation
+- Client ID is revoked or restricted
+
+### 429 Too Many Requests
+
+- Request rate exceeded for your credentials
+
+## Security Guidance
+
+- Keep API keys server-side and out of frontend bundles
+- Store credentials in environment variables or secret managers
+- Rotate compromised credentials immediately
+- Verify webhook signatures independently (webhook signing uses a separate secret)
+
+## Related Pages
-
- Set up real-time event notifications
+
+ Create credentials and manage webhook configuration.
-
-
- Make your first API call
+
+
+ Signature verification and delivery behavior.
-
-
- Manage your API keys and settings
+
+
+ Full endpoint authentication requirements.