AuthCentral/USER_MANAGEMENT_API.md

👥 Kullanıcı Yönetimi (Admin) API Dokümantasyonu

🔐 Default Admin Kullanıcı

Uygulama ilk kez çalıştırıldığında otomatik olarak bir admin kullanıcı oluşturulur:

Email: admin@gauth.local
Password: Admin@123
Role: admin

⚠️ Güvenlik Uyarısı: İlk giriş sonrası bu şifreyi mutlaka değiştirin!

---

🚀 Admin ile Giriş Yapma

curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@gauth.local",
    "password": "Admin@123"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUz...",
  "refresh_token": "eyJhbGciOiJIUz...",
  "user": {
    "id": "uuid",
    "email": "admin@gauth.local",
    "user_name": "admin",
    "roles": [
      {
        "name": "admin",
        "description": "Default admin role"
      }
    ]
  }
}

Not: Gelen access_token'ı tüm admin işlemlerde kullanacaksınız.

---

📍 User Management Endpoint'leri

Base URL: /v1/admin/users

Tüm endpoint'ler için gereklidir:

• ✅ Authentication (Bearer token)
• ✅ Admin rolü

---

1. Tüm Kullanıcıları Listele

GET /v1/admin/users
Authorization: Bearer {admin_token}

Query Parameters:

• page (optional): Sayfa numarası (default: 1)
• limit (optional): Sayfa başına kayıt (default: 10, max: 100)

Response (200):

{
  "users": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "user_name": "username",
      "email_verified": true,
      "created_at": "2026-02-04T00:00:00Z",
      "roles": [
        {
          "id": "uuid",
          "name": "user",
          "description": "Default user role"
        }
      ],
      "social_accounts": []
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

cURL Örneği:

TOKEN="your_admin_token_here"

curl -X GET "http://localhost:8080/v1/admin/users?page=1&limit=10" \
  -H "Authorization: Bearer $TOKEN"

---

2. Kullanıcı Ara

GET /v1/admin/users/search?q={search_query}
Authorization: Bearer {admin_token}

Query Parameters:

• q (required): Arama terimi (email veya username'de arar)
• page (optional): Sayfa numarası
• limit (optional): Sayfa başına kayıt

Response (200):

{
  "users": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "totalPages": 1
  }
}

cURL Örneği:

curl -X GET "http://localhost:8080/v1/admin/users/search?q=john&page=1&limit=10" \
  -H "Authorization: Bearer $TOKEN"

---

3. Kullanıcı Detayı

GET /v1/admin/users/{user_id}
Authorization: Bearer {admin_token}

Response (200):

{
  "id": "uuid",
  "email": "user@example.com",
  "user_name": "username",
  "email_verified": true,
  "created_at": "2026-02-04T00:00:00Z",
  "roles": [
    {
      "id": "uuid",
      "name": "user",
      "permissions": [
        {
          "name": "user:read",
          "description": "Can read user data"
        }
      ]
    }
  ],
  "social_accounts": [
    {
      "provider": "google",
      "provider_user_id": "123456"
    }
  ]
}

cURL Örneği:

curl -X GET "http://localhost:8080/v1/admin/users/UUID_HERE" \
  -H "Authorization: Bearer $TOKEN"

---

4. Yeni Kullanıcı Oluştur (Admin Oluşturma)

POST /v1/admin/users
Authorization: Bearer {admin_token}
Content-Type: application/json

Request Body:

{
  "email": "newadmin@example.com",
  "password": "SecurePass123!",
  "user_name": "newadmin",
  "email_verified": true,
  "roles": ["admin"]
}

Field Açıklamaları:

• email (required): Email adresi
• password (required): Şifre (min 6 karakter)
• user_name (required): Kullanıcı adı
• email_verified (optional): Email doğrulanmış mı? (default: false)
• roles (optional): Roller dizisi (default: ["user"])
  • Geçerli roller: "admin", "user"

Response (201):

{
  "id": "uuid",
  "email": "newadmin@example.com",
  "user_name": "newadmin",
  "email_verified": true,
  "roles": [
    {
      "id": "uuid",
      "name": "admin",
      "description": "Default admin role"
    }
  ],
  "created_at": "2026-02-04T00:00:00Z"
}

cURL Örneği - Yeni Admin Oluşturma:

curl -X POST http://localhost:8080/v1/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "yeni-admin@example.com",
    "password": "GuvenlıSifre123!",
    "user_name": "yeniadmin",
    "email_verified": true,
    "roles": ["admin"]
  }'

cURL Örneği - Normal Kullanıcı Oluşturma:

curl -X POST http://localhost:8080/v1/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "UserPass123!",
    "user_name": "normaluser",
    "email_verified": false,
    "roles": ["user"]
  }'

---

5. Kullanıcı Güncelle

PUT /v1/admin/users/{user_id}
Authorization: Bearer {admin_token}
Content-Type: application/json

Request Body (tüm alanlar optional):

{
  "email": "newemail@example.com",
  "password": "NewPassword123!",
  "user_name": "newusername",
  "email_verified": true,
  "roles": ["admin", "user"]
}

Response (200):

{
  "message": "User updated successfully",
  "user": {
    "id": "uuid",
    "email": "newemail@example.com",
    "username": "newusername",
    "email_verified": true,
    "roles": [
      {"name": "admin"},
      {"name": "user"}
    ],
    "updated_at": "2026-02-04T..."
  }
}

cURL Örneği:

# Sadece şifre değiştir
curl -X PUT "http://localhost:8080/v1/admin/users/UUID_HERE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "YeniSifre123!"
  }'

# Email doğrulaması aktif et
curl -X PUT "http://localhost:8080/v1/admin/users/UUID_HERE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_verified": true
  }'

# Kullanıcıyı admin yap (rol güncelleme)
curl -X PUT "http://localhost:8080/v1/admin/users/UUID_HERE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["admin"]
  }'

# Tüm bilgileri güncelle
curl -X PUT "http://localhost:8080/v1/admin/users/UUID_HERE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "beyhan@beyhan.dev",
    "user_name": "Beyhan Oğur",
    "roles": ["admin"],
    "email_verified": true
  }'

---

6. Kullanıcıya Roller Ata

POST /v1/admin/users/{user_id}/roles
Authorization: Bearer {admin_token}
Content-Type: application/json

Request Body:

{
  "roles": ["admin", "user"]
}

Response (200):

{
  "message": "Roles assigned successfully"
}

cURL Örneği - Kullanıcıyı Admin Yap:

curl -X POST "http://localhost:8080/v1/admin/users/UUID_HERE/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["admin"]
  }'

---

7. Kullanıcıdan Rol Kaldır

DELETE /v1/admin/users/{user_id}/roles/{role_name}
Authorization: Bearer {admin_token}

Response (200):

{
  "message": "Role removed successfully"
}

cURL Örneği - Admin Rolünü Kaldır:

curl -X DELETE "http://localhost:8080/v1/admin/users/UUID_HERE/roles/admin" \
  -H "Authorization: Bearer $TOKEN"

---

8. Kullanıcı Sil

DELETE /v1/admin/users/{user_id}
Authorization: Bearer {admin_token}

Response (200):

{
  "message": "User deleted successfully"
}

Not: Kendi hesabınızı silemezsiniz!

cURL Örneği:

curl -X DELETE "http://localhost:8080/v1/admin/users/UUID_HERE" \
  -H "Authorization: Bearer $TOKEN"

---

🔒 Admin Middleware

Tüm /v1/admin/* ve /v1/settings/* endpoint'leri için:

1. ✅ AuthMiddleware - Token kontrolü
2. ✅ AdminMiddleware - Admin rol kontrolü

Eğer kullanıcı admin rolüne sahip değilse:

{
  "error": "Admin access required"
}

---

📊 Kullanım Senaryoları

Senaryo 1: Yeni Admin Kullanıcı Oluşturma

# 1. Admin olarak giriş yap
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@gauth.local","password":"Admin@123"}'

# Response'dan access_token al
TOKEN="eyJhbGciOiJIUz..."

# 2. Yeni admin kullanıcı oluştur
curl -X POST http://localhost:8080/v1/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ikinci-admin@example.com",
    "password": "Admin@456",
    "user_name": "admin2",
    "email_verified": true,
    "roles": ["admin"]
  }'

# 3. Oluşturulan kullanıcı ile test et
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ikinci-admin@example.com","password":"Admin@456"}'

Senaryo 2: Normal Kullanıcıyı Admin Yap

# 1. Kullanıcıyı bul
curl -X GET "http://localhost:8080/v1/admin/users/search?q=user@example.com" \
  -H "Authorization: Bearer $TOKEN"

# Response'dan user ID'yi al
USER_ID="uuid-here"

# 2. Admin rolü ata
curl -X POST "http://localhost:8080/v1/admin/users/$USER_ID/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"roles": ["admin", "user"]}'

Senaryo 3: Kullanıcı Şifresini Sıfırla

curl -X PUT "http://localhost:8080/v1/admin/users/$USER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "YeniGeçiciSifre123!"
  }'

---

💻 Frontend Entegrasyonu

JavaScript Örneği

const API_BASE = 'http://localhost:8080/v1/admin';
const token = localStorage.getItem('access_token');

// User Management Class
class UserManagement {
  constructor(token) {
    this.token = token;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  // Tüm kullanıcıları getir
  async getAllUsers(page = 1, limit = 10) {
    const res = await fetch(`${API_BASE}/users?page=${page}&limit=${limit}`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return res.json();
  }

  // Kullanıcı ara
  async searchUsers(query, page = 1) {
    const res = await fetch(`${API_BASE}/users/search?q=${query}&page=${page}`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return res.json();
  }

  // Yeni admin kullanıcı oluştur
  async createAdmin(email, password, username) {
    const res = await fetch(`${API_BASE}/users`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        email,
        password,
        user_name: username,
        email_verified: true,
        roles: ['admin']
      })
    });
    return res.json();
  }

  // Kullanıcıyı admin yap
  async makeAdmin(userId) {
    const res = await fetch(`${API_BASE}/users/${userId}/roles`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        roles: ['admin']
      })
    });
    return res.json();
  }

  // Kullanıcı sil
  async deleteUser(userId) {
    const res = await fetch(`${API_BASE}/users/${userId}`, {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return res.json();
  }

  // Şifre sıfırla
  async resetPassword(userId, newPassword) {
    const res = await fetch(`${API_BASE}/users/${userId}`, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify({ password: newPassword })
    });
    return res.json();
  }
}

// Kullanım
const userMgmt = new UserManagement(token);

// Tüm kullanıcıları listele
userMgmt.getAllUsers(1, 10).then(data => {
  console.log('Users:', data.users);
  console.log('Total:', data.pagination.total);
});

// Yeni admin oluştur
userMgmt.createAdmin('yeni@admin.com', 'Secure123!', 'yeniadmin')
  .then(user => console.log('Admin created:', user));

// Kullanıcı ara
userMgmt.searchUsers('john').then(data => {
  console.log('Search results:', data.users);
});

---

🎯 Endpoint Özeti

Method	Endpoint	Açıklama
GET	/v1/admin/users	Tüm kullanıcıları listele
GET	/v1/admin/users/search	Kullanıcı ara
GET	/v1/admin/users/:id	Kullanıcı detayı
POST	/v1/admin/users	Yeni kullanıcı/admin oluştur
PUT	/v1/admin/users/:id	Kullanıcı güncelle
DELETE	/v1/admin/users/:id	Kullanıcı sil
POST	/v1/admin/users/:id/roles	Rol ata
DELETE	/v1/admin/users/:id/roles/:role	Rol kaldır

Toplam: 8 endpoint

---

⚠️ Önemli Notlar

1. Default Admin Şifresi: İlk giriş sonrası mutlaka değiştirin!
2. Kendi Hesabınızı Silemezsiniz: Sistem bunu engelleyecektir
3. Pagination: Max limit 100, default 10
4. Search: Email ve username alanlarında case-insensitive arama yapar
5. Roles: Sadece "admin" ve "user" rolleri vardır
6. Email Verified: Admin oluştururken true yapın ki direkt giriş yapabilsin

---

🎊 Başarıyla Tamamlandı!

Artık:

• ✅ Default admin kullanıcısı var
• ✅ Yeni admin kullanıcıları oluşturabilirsiniz
• ✅ Kullanıcıları yönetebilirsiniz
• ✅ Rolleri atayabilirsiniz
• ✅ Frontend'den kontrol edebilirsiniz

İlk adım:

# Admin ile giriş yap
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@gauth.local","password":"Admin@123"}'

İyi yönetimler! 👥