# Kimlik Doğrulama

Ideasoft API, kimlik doğrulama için **OAuth2** standardını kullanır. OAuth2; kullanıcı adı ve parola paylaşılmadan, gerekli parametreler gönderilerek hesap bilgilerine sınırlı erişim sağlayan bir yetkilendirme sistemidir.

- **authorizationUrl:** `https://magaza-adiniz.myideasoft.com/panel/auth`
- **tokenUrl:** `https://magaza-adiniz.myideasoft.com/oauth/v2/token`
- **akış:** `authorization_code`

:::note{title="Mağaza alan adınızı ayarlayın"}
Her istek **kendi mağazanızın** alan adına gider: `https://<mağaza>.myideasoft.com` ya da mağazanıza bağlı kendi alan adınız. Referanstaki örnekler `magaza-adiniz.myideasoft.com` yer tutucusunu gösterir; bir isteği denemek için **Test** düğmesine tıklayıp açılan penceredeki URL alanına kendi alan adınızı yazın — tarayıcınızda saklanır ve tüm isteklerde kullanılır. Endpoint URL'sinin yanındaki ayar simgesi de ("Edit server variables") aynı işi yapar.
:::

## Gerekli Bilgiler

Uygulamanızın yetkilendirilmesi için üç bilgiye ihtiyacınız vardır:

| Bilgi | Açıklama |
|---|---|
| **Client ID** | Uygulamanız için atanmış rastgele üretilmiş string. Bu bilgi açıktır. |
| **Client Secret** | Uygulamanız için özel üretilmiş string. Bu bilgi gizli tutulmalıdır. |
| **Redirect URL** | Kullanıcının uygulamanıza yetki verdikten sonra geri dönmesi gereken adres. |

:::info{title="Kayıt"}
Bu üç bilginin de önceden sistemde kayıtlı olması gerekir. Admin panelinden **Entegrasyonlar → API → Ekle** yolu izlendiğinde "Redirect URL" kullanıcının tercihine göre girilir; "Client ID" ve "Client Secret" ise sistem tarafından otomatik üretilir.
:::

## Yetkilendirme İşlemleri

`authorization_code` yönteminde kullanıcı özel bir sayfaya yönlendirilir ve uygulamaya izin vermesi istenir; kullanıcı adı ve parola gerekmez. İşlem dört aşamada gerçekleştirilir. Bu aşamalar her uygulama için yalnızca bir kez izlenir ve uygulamaya gerekli izinleri verme yetkisi yalnızca mağaza yöneticisindedir.

### 1. Yetki sayfasına geliş

Kullanıcıyı, uygulamanızı tanımlayan bilgilerle birlikte yetki sayfasına yönlendirin:

```http
GET https://magaza-adiniz.myideasoft.com/panel/auth
```

| Parametre | Açıklama |
|---|---|
| `client_id` | Yukarıda tanımlanan Client ID değeri |
| `response_type` | Doğrulama için kullanılacak yöntem. Geçerli değer: `code` |
| `state` | İstek için rastgele üretilmiş kod (3. adımda kontrol edilmelidir) |
| `redirect_uri` | Yukarıda tanımlanan Redirect URL değeri; onay sonrası kullanıcı bu adrese yönlendirilir |

İzinler (scope) istek başına istenmez; mağaza panelinde (Entegrasyonlar → API) oluşturulan API tanımıyla sabittir.

Örnek istek:

```http
GET https://magaza-adiniz.myideasoft.com/panel/auth
  ?client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f
  &response_type=code
  &state=2b33fdd45jbevd6nam
  &redirect_uri=https://client.example-app.com/auth
```

### 2. Yetki izni sayfası

Kullanıcı Ideasoft admin panelindeki yetki izin ekranına gelir. Burada uygulamanızın adı ve izinleri görülür; kullanıcı uygulamaya yetki verebilir veya reddedebilir.

### 3. Uygulama sayfasına geri dönüş

Kullanıcı, `redirect_uri` adresine yönlendirilir. Duruma göre `GET` parametrelerinde aşağıdaki değerler bulunur; uygulamanız bu değerleri dikkate alarak token alma veya hata işleme adımlarını gerçekleştirmelidir.

| Parametre | Açıklama |
|---|---|
| `code` | 4. adımda token almak için kullanılacak kimlik doğrulama kodu. **Geçerlilik süresi 30 saniyedir.** |
| `state` | 1. adımda verilen kod. MITM tipi saldırılardan korunmak için doğruluğunu kontrol etmeniz gerekir. |
| `error` | Hata kodu (yalnızca hata durumunda gönderilir) |
| `error_description` | Hata açıklaması (yalnızca hata durumunda gönderilir) |

Başarılı dönüş örneği:

```http
GET https://client.example-app.com/auth
  ?state=2b33fdd45jbevd6nam
  &code=Q0ODMI2OGYjMjBkN2mJmYzNkOTE4gzMGRhZDZTcykyOGQ3M2M2YTU2ZGVlMzE2MzB2MYkc5NWzE0ZWNiYjI2MA
```

Hata durumunda dönebilecek değerler:

| error | Açıklama |
|---|---|
| `invalid_grant` | Kullanılan yetkilendirme yöntemi geçersiz |
| `access_denied` | Kullanıcı uygulamanıza yetki vermemeyi seçti |

Başarısız dönüş örneği:

```http
GET https://client.example-app.com/auth
  ?error=access_denied
  &error_description=The%20user%20denied%20access%20to%20your%20application
  &state=2b33fdd45jbevd6nam
```

### 4. Token isteği

Bu adımda uygulama, kullanıcıdan bağımsız olarak sunucuya doğrudan istek göndererek Access Token ve Refresh Token alır.

```http
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
```

| Parametre | Açıklama |
|---|---|
| `grant_type` | Doğrulama yöntemi. Geçerli değer: `authorization_code` |
| `client_id` | Client ID değeri |
| `client_secret` | Client Secret değeri |
| `code` | 3. adımda elde edilen kimlik doğrulama kodu |
| `redirect_uri` | Redirect URL değeri |

Örnek istek (form gövdesi olarak gönderin; aynı parametreler query string olarak da kabul edilir):

```http
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f
&client_secret=1sowg0oogc4wg4w4o4gh4va57gggwskkgo08m44ksog8kmu88o
&code=Q0ODMI2OGYjMjBkN2mJmYzNkOTE4gzMGRhZDZTcykyOGQ3M2M2YTU2ZGVlMzE2MzB2MYkc5NWzE0ZWNiYjI2MA
&redirect_uri=https%3A//client.example-app.com%2Fauth%2F
```

Başarılı istek `HTTP 200` ile şuna benzer bir JSON döner:

```json
{
  "access_token": "OGE3MzkxNDlhOGY0M2RjZWM1MWI2MWIxZjRmNDJhZThiOGJkOWZlMWIwNzVkYWFlOWFiMDAxYzkwMDlmMDhlMw",
  "expires_in": 86400,
  "token_type": "bearer",
  "scope": "Sahip olduğunuz izinler burada görüntülenecektir.",
  "refresh_token": "NjczY2E2NzZiNDJjZWI5NTE2YjZhNTlhYTJmOTQ5MjljN2MwNmUxM2MzODc5YTE4OGVjMDdlYTBiMzY1MWI1Mw"
}
```

Başarısız istek `HTTP 400` ile `error` ve `error_description` alanları içeren bir JSON döner. Olası hatalar:

| error | error_description | Açıklama |
|---|---|---|
| `invalid_request` | *Invalid grant_type parameter or parameter missing* | `grant_type` değeri eksik veya geçersiz |
| `invalid_request` | *Missing parameter. "code" is required* | `code` değeri eksik |
| `invalid_request` | *The redirect URI parameter is required* | `redirect_uri` değeri eksik |
| `unauthorized_client` | *The grant type is unauthorized for this client_id* | Kullanılan `grant_type` uygulamanız için geçersiz |
| `invalid_client` | *The client credentials are invalid* | Verilen `client_id` veya `client_secret` doğru değil |
| `invalid_grant` | *Code doesn't exist or is invalid for the client* | Verilen `code` değeri doğru değil |
| `redirect_uri_mismatch` | *The redirect URI is missing or do not match* | `redirect_uri` değeri doğru değil |
| `invalid_grant` | *The authorization code has expired* | Verilen `code` değerinin kullanım süresi dolmuş |

## Token Geçerliliği

Alınan **Access Token** sonraki tüm API çağrılarında kullanılır; geçerlilik süresi **24 saat**'tir.

Access Token'ın süresi dolduğunda **Refresh Token** ile yeni bir Access Token alınabilir:

```http
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f
&client_secret=1sowg0oogc4wg4w4o4gh4va57gggwskkgo08m44ksog8kmu88o
&refresh_token=NjczY2E2NzZiNDJjZWI5NTE2YjZhNTlhYTJmOTQ5MjljN2MwNmUxM2MzODc5YTE4OGVjMDdlYTBiMzY1MWI1Mw
```

Refresh Token ile yapılan her Access Token talebinde Refresh Token da **yenilenir** (rotate edilir). Doğru bir kurguyla iki token düzenli yenilenirse yeniden yetkilendirme gerekmez. Refresh Token geçerlilik süresi **2 ay**'dır; bu süreden sonra kullanıcının yeniden yetki vermesi gerekir.

## API Çağrısı

Access token'ı her istekte `Authorization` başlığı ile gönderin:

```http
Authorization: Bearer <access_token>
```

Access token'ın yetkileri, mağaza panelindeki API tanımıyla belirlenir (istek başına scope gönderilmez); tüm scope listesi için [Admin API](/admin-api) spec'indeki güvenlik tanımına bakın. Endpoint ve alan detayları için [OAuth referansına](/oauth) bakın.

## Postman ile örnek yetkilendirme

Postman'de yetkilendirme adımları şöyledir:

1. İstekte **Authorization** sekmesinden **OAuth 2.0** seçilir.
2. Grant type olarak **Authorization Code** (`authorization_code`) ve Callback URL olarak `https://www.getpostman.com/oauth2/callback` girilir. Callback URL, admin panelindeki Redirect URL değeriyle aynı tanımlanmalıdır.
3. **Auth URL:** `https://magaza-adiniz.myideasoft.com/panel/auth`, **Access Token URL:** `https://magaza-adiniz.myideasoft.com/oauth/v2/token` olarak doldurulur.
4. **Client ID** ve **Client Secret** değerleri, admin panelinde tanımladığınız API bilgilerinden alınır.
5. **Get New Access Token** butonu ile yetki sayfasına yönlendirilip, gerekli izinleri tanımladığınız kullanıcı ile giriş yapılır. İzinler kabul edildikten sonra Access Token Postman'de kullanılabilir hale gelir.

:::warning{title="Eski yetkilendirme"}
v8.0 öncesinde `/admin/user/auth` adresinde bulunan eski yetkilendirme endpoint'i kaldırılmıştır; yalnızca `/panel/auth` kullanılmalıdır.
:::
