atahango/belgeler/CORS_API_DOCUMENTATION.md

CORS Whitelist & Blacklist API Dokümantasyonu

📋 Genel Bakış

AuthCentral'da CORS (Cross-Origin Resource Sharing) yönetimi için Whitelist ve Blacklist sistemleri mevcuttur.

Özellikler:

• ✅ CRUD operasyonları (Create, Read, Update, Delete)
• ✅ Redis cache desteği
• ✅ Admin only endpoints
• ✅ Active/Inactive durumları
• ✅ Audit trail (created_by, updated_by)

---

🔐 Authentication

Tüm endpoint'ler Admin yetkisi gerektirir:

Authorization: Bearer {admin_access_token}

---

📡 CORS Whitelist API

1. Tüm Whitelist Kayıtlarını Listele

GET /v1/settings/cors/whitelist

Headers:

Authorization: Bearer {token}

Yanıt:

[
  {
    "id": "uuid",
    "origin": "http://localhost:3000",
    "description": "Development frontend",
    "is_active": true,
    "created_by": "admin@gauth.local",
    "created_at": "2026-02-05T10:00:00Z",
    "updated_at": "2026-02-05T10:00:00Z"
  },
  {
    "id": "uuid",
    "origin": "https://myapp.com",
    "description": "Production frontend",
    "is_active": true,
    "created_by": "admin@gauth.local",
    "created_at": "2026-02-05T09:00:00Z",
    "updated_at": "2026-02-05T09:00:00Z"
  }
]

2. Whitelist Kaydı Oluştur

POST /v1/settings/cors/whitelist

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Body:

{
  "origin": "https://example.com",
  "description": "Customer frontend application"
}

Başarılı Yanıt (201):

{
  "id": "new-uuid",
  "origin": "https://example.com",
  "description": "Customer frontend application",
  "is_active": true,
  "created_by": "admin@gauth.local",
  "created_at": "2026-02-05T11:00:00Z",
  "updated_at": "2026-02-05T11:00:00Z"
}

3. Whitelist Kaydını Güncelle

PUT /v1/settings/cors/whitelist/{id}

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Body (tüm alanlar opsiyonel):

{
  "origin": "https://new-domain.com",
  "description": "Updated description",
  "is_active": false
}

Başarılı Yanıt (200):

{
  "message": "Whitelist updated successfully"
}

4. Whitelist Kaydını Sil

DELETE /v1/settings/cors/whitelist/{id}

Headers:

Authorization: Bearer {token}

Başarılı Yanıt (200):

{
  "message": "Whitelist entry deleted successfully"
}

---

🚫 CORS Blacklist API

1. Tüm Blacklist Kayıtlarını Listele

GET /v1/settings/cors/blacklist

Headers:

Authorization: Bearer {token}

Yanıt:

[
  {
    "id": "uuid",
    "origin": "https://malicious-site.com",
    "reason": "Security threat detected",
    "is_active": true,
    "created_by": "admin@gauth.local",
    "created_at": "2026-02-05T10:00:00Z",
    "updated_at": "2026-02-05T10:00:00Z"
  }
]

2. Blacklist Kaydı Oluştur

POST /v1/settings/cors/blacklist

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Body:

{
  "origin": "https://spam-domain.com",
  "reason": "Spam attempts detected"
}

Başarılı Yanıt (201):

{
  "id": "new-uuid",
  "origin": "https://spam-domain.com",
  "reason": "Spam attempts detected",
  "is_active": true,
  "created_by": "admin@gauth.local",
  "created_at": "2026-02-05T11:00:00Z",
  "updated_at": "2026-02-05T11:00:00Z"
}

3. Blacklist Kaydını Güncelle

PUT /v1/settings/cors/blacklist/{id}

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Body (tüm alanlar opsiyonel):

{
  "origin": "https://updated-domain.com",
  "reason": "Updated reason",
  "is_active": false
}

Başarılı Yanıt (200):

{
  "message": "Blacklist updated successfully"
}

4. Blacklist Kaydını Sil

DELETE /v1/settings/cors/blacklist/{id}

Headers:

Authorization: Bearer {token}

Başarılı Yanıt (200):

{
  "message": "Blacklist entry deleted successfully"
}

---

🧪 Kullanım Örnekleri

Tam İş Akışı (cURL)

#!/bin/bash

# 1. Admin Login
TOKEN=$(curl -s -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@gauth.local","password":"Admin@123"}' | jq -r '.access_token')

echo "Token: ${TOKEN:0:30}..."

# 2. Whitelist'e domain ekle
echo -e "\n=== Create Whitelist Entry ==="
curl -X POST http://localhost:8080/v1/settings/cors/whitelist \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://myapp.com",
    "description": "Production app"
  }' | jq .

# 3. Tüm whitelist'i listele
echo -e "\n=== List All Whitelist ==="
curl -X GET http://localhost:8080/v1/settings/cors/whitelist \
  -H "Authorization: Bearer $TOKEN" | jq .

# 4. Blacklist'e domain ekle
echo -e "\n=== Create Blacklist Entry ==="
curl -X POST http://localhost:8080/v1/settings/cors/blacklist \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://spam.com",
    "reason": "Spam detected"
  }' | jq .

# 5. Whitelist entry'yi güncelle (ID'yi yukarıdaki response'dan alın)
WHITELIST_ID="your-whitelist-id-here"
echo -e "\n=== Update Whitelist Entry ==="
curl -X PUT "http://localhost:8080/v1/settings/cors/whitelist/$WHITELIST_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "is_active": true
  }' | jq .

# 6. Blacklist entry'yi sil
BLACKLIST_ID="your-blacklist-id-here"
echo -e "\n=== Delete Blacklist Entry ==="
curl -X DELETE "http://localhost:8080/v1/settings/cors/blacklist/$BLACKLIST_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

---

🎯 Frontend Entegrasyonu (React)

API Client

class CorsSettingsAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
  }

  // ====== Whitelist ======
  
  async getWhitelist() {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/whitelist`, {
      headers: {
        'Authorization': `Bearer ${this.token}`
      }
    });
    return response.json();
  }

  async createWhitelist(origin, description) {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/whitelist`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ origin, description })
    });
    return response.json();
  }

  async updateWhitelist(id, updates) {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/whitelist/${id}`, {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    });
    return response.json();
  }

  async deleteWhitelist(id) {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/whitelist/${id}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${this.token}`
      }
    });
    return response.json();
  }

  // ====== Blacklist ======
  
  async getBlacklist() {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/blacklist`, {
      headers: {
        'Authorization': `Bearer ${this.token}`
      }
    });
    return response.json();
  }

  async createBlacklist(origin, reason) {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/blacklist`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ origin, reason })
    });
    return response.json();
  }

  async updateBlacklist(id, updates) {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/blacklist/${id}`, {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    });
    return response.json();
  }

  async deleteBlacklist(id) {
    const response = await fetch(`${this.baseURL}/v1/settings/cors/blacklist/${id}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${this.token}`
      }
    });
    return response.json();
  }
}

// Kullanım
const api = new CorsSettingsAPI('http://localhost:8080', YOUR_ADMIN_TOKEN);

// Whitelist listele
const whitelists = await api.getWhitelist();
console.log(whitelists);

// Yeni whitelist ekle
const newEntry = await api.createWhitelist('https://newapp.com', 'New application');
console.log(newEntry);

React Component Örneği

import React, { useState, useEffect } from 'react';

function CorsWhitelistManager() {
  const [whitelists, setWhitelists] = useState([]);
  const [newOrigin, setNewOrigin] = useState('');
  const [newDescription, setNewDescription] = useState('');
  const token = localStorage.getItem('admin_token');

  useEffect(() => {
    fetchWhitelists();
  }, []);

  const fetchWhitelists = async () => {
    try {
      const response = await fetch('http://localhost:8080/v1/settings/cors/whitelist', {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      });
      const data = await response.json();
      setWhitelists(data);
    } catch (error) {
      console.error('Error fetching whitelists:', error);
    }
  };

  const handleCreate = async (e) => {
    e.preventDefault();
    try {
      const response = await fetch('http://localhost:8080/v1/settings/cors/whitelist', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          origin: newOrigin,
          description: newDescription
        })
      });
      
      if (response.ok) {
        setNewOrigin('');
        setNewDescription('');
        fetchWhitelists(); // Refresh list
        alert('Whitelist entry created!');
      }
    } catch (error) {
      console.error('Error creating whitelist:', error);
    }
  };

  const handleDelete = async (id) => {
    if (!confirm('Are you sure you want to delete this entry?')) return;
    
    try {
      const response = await fetch(`http://localhost:8080/v1/settings/cors/whitelist/${id}`, {
        method: 'DELETE',
        headers: {
          'Authorization': `Bearer ${token}`
        }
      });
      
      if (response.ok) {
        fetchWhitelists(); // Refresh list
        alert('Whitelist entry deleted!');
      }
    } catch (error) {
      console.error('Error deleting whitelist:', error);
    }
  };

  const toggleActive = async (id, currentStatus) => {
    try {
      const response = await fetch(`http://localhost:8080/v1/settings/cors/whitelist/${id}`, {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          is_active: !currentStatus
        })
      });
      
      if (response.ok) {
        fetchWhitelists(); // Refresh list
      }
    } catch (error) {
      console.error('Error updating whitelist:', error);
    }
  };

  return (
    <div className="cors-whitelist-manager">
      <h2>CORS Whitelist Manager</h2>
      
      {/* Add New Entry Form */}
      <form onSubmit={handleCreate} className="add-form">
        <input
          type="text"
          placeholder="Origin (e.g., https://example.com)"
          value={newOrigin}
          onChange={(e) => setNewOrigin(e.target.value)}
          required
        />
        <input
          type="text"
          placeholder="Description"
          value={newDescription}
          onChange={(e) => setNewDescription(e.target.value)}
        />
        <button type="submit">Add to Whitelist</button>
      </form>

      {/* Whitelist Table */}
      <table>
        <thead>
          <tr>
            <th>Origin</th>
            <th>Description</th>
            <th>Active</th>
            <th>Created By</th>
            <th>Actions</th>
          </tr>
        </thead>
        <tbody>
          {whitelists.map(entry => (
            <tr key={entry.id}>
              <td>{entry.origin}</td>
              <td>{entry.description}</td>
              <td>
                <button onClick={() => toggleActive(entry.id, entry.is_active)}>
                  {entry.is_active ? '✅ Active' : '❌ Inactive'}
                </button>
              </td>
              <td>{entry.created_by}</td>
              <td>
                <button onClick={() => handleDelete(entry.id)}>Delete</button>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

export default CorsWhitelistManager;

---

📊 API Endpoints Özeti

Endpoint	Method	Açıklama	Admin Required
/v1/settings/cors/whitelist	GET	Whitelist listele	✅
/v1/settings/cors/whitelist	POST	Whitelist ekle	✅
/v1/settings/cors/whitelist/:id	PUT	Whitelist güncelle	✅
/v1/settings/cors/whitelist/:id	DELETE	Whitelist sil	✅
/v1/settings/cors/blacklist	GET	Blacklist listele	✅
/v1/settings/cors/blacklist	POST	Blacklist ekle	✅
/v1/settings/cors/blacklist/:id	PUT	Blacklist güncelle	✅
/v1/settings/cors/blacklist/:id	DELETE	Blacklist sil	✅

---

🔧 Cache Yönetimi

CORS ayarları Redis'te cache'lenir:

• Cache süresi: 1 saat
• Otomatik invalidation: Create/Update/Delete işlemlerinde
• Cache key:
  • Whitelist: cors:whitelist
  • Blacklist: cors:blacklist

---

✅ Test Checklist

• Admin token alındı
• Whitelist ekleme testi
• Whitelist listeleme testi
• Whitelist güncelleme testi
• Whitelist silme testi
• Blacklist ekleme testi
• Blacklist listeleme testi
• Blacklist güncelleme testi
• Blacklist silme testi
• Swagger dokümantasyonu kontrol edildi

CORS Whitelist & Blacklist API'leri tam çalışır durumda! 🚀