# Kimlik Doğrulama

Yolcu360 Agency API, güvenli erişim için JWT (JSON Web Token) tabanlı kimlik doğrulama kullanır. API'ye erişmek için
önce API kimlik bilgilerinizle kimlik doğrulaması yapmanız ve bir erişim jetonu almanız gerekir.

## Kimlik Doğrulama Akışı

1. **API Kimlik Bilgilerini Alın**: Acente portalından API anahtarınızı ve gizli anahtarınızı edinin
2. **Giriş Yapın**: `/auth/login` kullanarak kimlik bilgilerinizi JWT jetonlarıyla değiştirin
3. **Erişim Jetonunu Kullanın**: Tüm API çağrıları için Authorization başlığında erişim jetonunu ekleyin
4. **Jetonları Yenileyin**: Süresi dolduğunda yeni erişim jetonları almak için yenileme jetonunu kullanın


## API Anahtarı ile Giriş

API Anahtarınız ve Gizli Anahtarınızı kullanarak JWT jetonları alma süreci.

### Endpoint

```
POST /auth/login
```

### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `key` | string | Evet | Acente portalından aldığınız API Anahtarınız |
| `secret` | string | Evet | Acente portalından aldığınız API Gizli Anahtarınız |


### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "key": "api_anahtariniz_buraya",
    "secret": "api_gizli_anahtariniz_buraya"
  }'
```

### Yanıt

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

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpc2lzYXJlZnJlc2h0b2tlbg...",
  "accessTokenExpireAt": "2024-12-26T10:30:00Z",
  "refreshTokenExpireAt": "2024-12-27T10:00:00Z",
  "user": {
    "id": "user_123456",
    "email": "agency@example.com",
    "firstName": "Ahmet",
    "lastName": "Yılmaz"
  }
}
```

**Hata Yanıtları:**

- `400 Bad Request`: Geçersiz istek formatı veya eksik alanlar
- `401 Unauthorized`: Geçersiz API anahtarı veya gizli anahtar
- `500 Internal Server Error`: Sunucu hatası


## Erişim Jetonunu Yenileme

Erişim jetonunuzun süresi dolduğunda, kullanıcının API kimlik bilgileriyle yeniden kimlik doğrulaması yapmasını
gerektirmeden yeni bir erişim jetonu almak için yenileme jetonunu kullanın.

### Endpoint

```
POST /auth/refresh
```

### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `token` | string | Evet | Giriş yanıtından geçerli yenileme jetonu |


### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "token": "dGhpc2lzYXJlZnJlc2h0b2tlbg..."
  }'
```

### Yanıt

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

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "bmV3cmVmcmVzaHRva2VuaGVyZQ...",
  "accessTokenExpireAt": "2024-12-26T11:30:00Z",
  "refreshTokenExpireAt": "2024-12-27T11:00:00Z",
  "user": {
    "id": "user_123456",
    "email": "agency@example.com",
    "firstName": "Ahmet",
    "lastName": "Yılmaz"
  }
}
```

**Hata Yanıtları:**

- `400 Bad Request`: Geçersiz istek formatı veya eksik jeton
- `401 Unauthorized`: Geçersiz veya süresi dolmuş yenileme jetonu
- `500 Internal Server Error`: Sunucu hatası


## Erişim Jetonlarını Kullanma

Bir erişim jetonunuz olduğunda, tüm API istekleri için `Authorization` başlığına ekleyin:

### Authorization Başlık Formatı

```
Authorization: Bearer ERIŞIM_JETONUNUZ
```

### Örnek API Çağrısı

```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/locations?query=istanbul \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Jeton Süresi ve En İyi Uygulamalar

### Erişim Jetonu Yaşam Döngüsü

- **Erişim Jetonu Süresi**: Erişim jetonları 1 hafta içinde sona erer
- **Yenileme Jetonu Süresi**: Yenileme jetonları 1 ay içinde sona erer
- **Otomatik Yenileme**: Uygulamanızda otomatik jeton yenileme işlemini uygulayın


### Uygulama En İyi Uygulamaları

1. **Jetonları Güvenli Saklayın**: Jetonları hiçbir zaman istemci tarafı kodda veya günlüklerde saklamayın
2. **Süre Dolumunu Ele Alın**: 401 hataları aldığınızda otomatik yenileme mantığını uygulayın
3. **Süre Dolum Zamanlarını İzleyin**: Proaktif yenileme için `accessTokenExpireAt` alanını kullanın
4. **Güvenli İletim**: Kimlik doğrulama istekleri için her zaman HTTPS kullanın


### Örnek Jeton Yenileme Mantığı

```javascript
async function makeApiRequest(url, options = {}) {
    let token = getStoredAccessToken();

    // Jetonun süresi dolmak üzere mi kontrol et
    if (isTokenNearExpiry(token)) {
        token = await refreshAccessToken();
    }

    const response = await fetch(url, {
        ...options,
        headers: {
            ...options.headers,
            'Authorization': `Bearer ${token}`
        }
    });

    // Süresi dolmuş jetonu ele al
    if (response.status === 401) {
        token = await refreshAccessToken();
        return fetch(url, {
            ...options,
            headers: {
                ...options.headers,
                'Authorization': `Bearer ${token}`
            }
        });
    }

    return response;
}

async function refreshAccessToken() {
    const refreshToken = getStoredRefreshToken();

    const response = await fetch('/api/v1/auth/refresh', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({token: refreshToken})
    });

    if (!response.ok) {
        // Yenileme jetonunun süresi doldu, yeniden kimlik doğrulaması gerekli
        throw new Error('Kimlik doğrulaması gerekli');
    }

    const data = await response.json();
    storeTokens(data.accessToken, data.refreshToken);
    return data.accessToken;
}
```

## Güvenlik Değerlendirmeleri

### API Anahtarı Güvenliği

- **API anahtarlarını asla açığa çıkarmayın**: API anahtarlarını istemci tarafı kodda, günlüklerde veya sürüm
kontrolünde bulundurmayın
- **Anahtarları düzenli olarak değiştirin**: Periyodik olarak yeni API anahtarları oluşturun
- **Ortam değişkenlerini kullanın**: API kimlik bilgilerini güvenli ortam değişkenlerinde saklayın
- **Anahtar izinlerini sınırlayın**: API anahtarlarınız için gereken minimum izinleri kullanın


### Jeton Güvenliği

- **Güvenli depolama**: Jetonları güvenli, şifrelenmiş depolamada saklayın
- **Yalnızca HTTPS**: API iletişimleri için her zaman HTTPS kullanın
- **Jeton kapsamı**: Erişim jetonları organizasyonunuzun kaynaklarıyla sınırlıdır
- **Çıkış işlemi**: Kullanıcılar çıkış yaptığında saklanan jetonları temizleyin


## Hata Kodları

| Kod | Açıklama |
|  --- | --- |
| 1001 | Geçersiz istek formatı |
| 1002 | Geçersiz API anahtarı veya gizli anahtar |
| 1003 | API anahtarı devre dışı veya askıya alınmış |
| 1004 | Geçersiz veya süresi dolmuş yenileme jetonu |
| 1005 | Hız sınırı aşıldı |
| 1500 | Dahili sunucu hatası |


## Sorun Giderme

### Yaygın Sorunlar

**Geçersiz API Anahtarı Hatası**

- API anahtarınızın ve gizli anahtarınızın doğru olduğunu doğrulayın
- API anahtarınızın acente portalında aktif olup olmadığını kontrol edin
- Doğru ortamı kullandığınızdan emin olun (test vs üretim)


**Jeton Süresi Doldu Hatası**

- Otomatik jeton yenileme mantığını uygulayın
- İstek yapmadan önce jeton süre dolum zamanlarını kontrol edin
- Jetonları yenileyerek 401 yanıtlarını ele alın