# Netgsm Authorization API

> Bu API ile kullanıcı adı ve şifrenizle token alabilir, süresi dolmadan token'larınızı yenileyebilirsiniz.

- **Sürüm:** 3.0
- **Canlı ortam:** `https://ext-api.netgsm.com.tr/auth/v3`
- **Sandbox:** `https://ext-sandbox.netgsm.com.tr/auth/v3`
- **OpenAPI tanımı:** https://api-docs.netgsm.com.tr/openapi/auth-v3.yaml
- **HTML sayfası:** https://api-docs.netgsm.com.tr/auth/netgsm-authorization-api/

Bu API ile kullanıcı adı ve şifrenizle token alabilir, süresi dolmadan token'larınızı
yenileyebilirsiniz. Aldığınız `access_token`'ı diğer Netgsm API'lerinde (örneğin SMS API)
`Authorization: Bearer <access_token>` başlığıyla gönderirsiniz.

## İstek ve yanıt biçimi

- İstekler yalnızca HTTPS üzerinden gönderilir.
- Gövde `application/json` ya da `application/x-www-form-urlencoded` olabilir. Alanlar
  yalnızca gövdede gönderilir; `username`, `password` veya `refresh_token` query string'de
  gönderilirse istek `422` ile reddedilir.
- Başarılı yanıtlar `application/json` türündedir ve kaynağı doğrudan döner; zarf yoktur.
- Tüm yanıtlar `Cache-Control: no-store` ve `Pragma: no-cache` başlıklarıyla döner.
- İstek gövdesi en fazla 1 MB olabilir.

## Hatalar

Hatalar `application/problem+json` türünde, RFC 9457 yapısında döner. İstemci mantığınızı
`code` alanına göre kurmalısınız. Destek ekibine yazarken yanıttaki `request_id` değerini
(`X-Thread-Id` yanıt başlığıyla aynıdır) paylaşmanız, isteğinizi kayıtlarda hızlıca bulmamızı
sağlar.

İsteğinizden kaynaklanan tüm hatalar `4xx` döner; `5xx` yalnızca sistemler arası hatalarda
döner.

Her uç noktada karşılaşabileceğiniz genel hatalar:

| Durum | Kod | Ne zaman |
|---|---|---|
| 403 | `https_required` | İstek HTTPS değil. |
| 404 | `not_found` | Adres yok. |
| 405 | `method_not_allowed` | Adres bu metodu desteklemiyor. Desteklenen metotlar `Allow` başlığındadır. |
| 413 | `payload_too_large` | Gövde 1 MB'ı aşıyor. |
| 500 | `internal_error` | Beklenmeyen hata. |

## Limitler

Tüm limitler dakika bazlıdır.

| Kapsam | Limit | Anahtar |
|---|---|---|
| `POST /token` | 30 istek / dakika | IP |
| Hatalı giriş | 5 deneme / dakika; başarılı giriş sayacı sıfırlar | Kullanıcı adı + IP |
| `POST /token/refresh` | 60 istek / dakika | IP |

Limitli uçların yanıtları `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` ve
`RateLimit-Policy` başlıklarını içerir. Limit aşıldığında `429` döner; `Retry-After`
başlığındaki süre (saniye) kadar beklemelisiniz.

## Uç noktalar

### Token

Kullanıcı adı ve şifreyle token alma ve refresh token ile token yenileme.

- [`POST /token` Token alma](https://api-docs.netgsm.com.tr/auth/create-token.md): username ve password doğrulanır; başarılıysa bir access token ve bir refresh token döner.
- [`POST /token/refresh` Token yenileme](https://api-docs.netgsm.com.tr/auth/refresh-token.md): Refresh token ile yeni bir token çifti üretir.