Token alma

POST 
/token

İstek: POST https://ext-api.netgsm.com.tr/auth/v3/token
Canlı ortam: https://ext-api.netgsm.com.tr/auth/v3
Sandbox: https://ext-sandbox.netgsm.com.tr/auth/v3

username ve password doğrulanır; başarılıysa bir access token ve bir refresh token döner. Token istenen scope ile verilir.

Scope

scope boşlukla ayrılmış bir veya daha fazla değerdir (RFC 6749 §3.3). Yalnızca aşağıdaki değerler kabul edilir; boş ya da tanınmayan bir değer (örneğin all) içeren istek 422 validation_failed döner ve errors.scope izin verilen değerleri listeler. Tekrar eden değerler yok sayılır.

scope	Kapsam
profile	Temel hesap bilgileri
contact	İletişim bilgileri
email	E-posta adresi
sms	SMS hizmeti (gönderim veya alım)
sms:send	SMS gönderimi
sms:receive	Gelen SMS
sms:send:gsm	GSM SMS gönderimi
sms:receive:gsm	GSM gelen SMS
voice	Ses hizmetleri (giden veya gelen arama)
voice:outgoing	Giden sesli arama
voice:incoming	Gelen sesli arama
voice:outgoing:gsm	GSM giden sesli arama
voice:incoming:gsm	GSM gelen sesli arama
voice-sms	Telesekreter hizmeti
voicemail	Sesli mesaj hizmeti
fax	Faks hizmeti (gönderim veya alım)
fax:send	Faks gönderimi
fax:receive	Gelen faks
netsantral	Netsantral hizmeti
netasistan	Netasistan hizmeti
digital-services	Dijital hizmetler
financial	Finansal bilgiler

• Alt kapsamlar (hizmet:işlem) hizmetin yalnızca o işlemini kapsar. GSM hizmetleri ayrıdır (hizmet:işlem:gsm); sms ve voice GSM'i kapsamaz.
• Bir hizmet kapsamı (sms) aynı hizmetin bir alt kapsamıyla (sms:send, sms:send:gsm) birlikte istenirse yok sayılır; token alt kapsamla verilir ve yanıttaki scope bunu gösterir.
• Hizmet kapsamları için hizmetin hesabınızda aktif olması, alt kullanıcıyla girişte alt kullanıcının o hizmete yetkili olması gerekir. Sağlanmazsa token verilmez: 403 service_not_activated ya da sub_user_not_permitted, denied_scopes alanında ilgili kapsamlarla.

İstemcinin IP adresi, ülkesi ve User-Agent bilgisi güvenlik kontrolleri (IP izinleri, risk analizi, yurt dışı erişim) için kullanılır.

Limit: IP başına dakikada 30 istek. Hatalı girişler ayrıca kullanıcı adı + IP başına dakikada 5 denemeyle sınırlıdır; başarılı bir giriş bu sayacı sıfırlar.

Request

application/json

Bodyrequired

usernamestringrequired
Kullanıcı adı.
Possible values: <= 255 characters
Example: 312XXXXXXX
passwordpasswordrequired
Şifre.
Possible values: <= 255 characters
Example: XXXXXXX
scopestringrequired
İstenen kapsamlar, boşlukla ayrılmış. İzin verilen değerler uç noktanın açıklamasındaki tablodadır.
Possible values: <= 255 characters
Example: sms:send sms:receive

application/x-www-form-urlencoded

Bodyrequired

usernamestringrequired
Kullanıcı adı.
Possible values: <= 255 characters
Example: 312XXXXXXX
passwordpasswordrequired
Şifre.
Possible values: <= 255 characters
Example: XXXXXXX
scopestringrequired
İstenen kapsamlar, boşlukla ayrılmış. İzin verilen değerler uç noktanın açıklamasındaki tablodadır.
Possible values: <= 255 characters
Example: sms:send sms:receive

Responses

200

Token verildi.

Response Headers

Cache-Control

Her zaman no-store.

Pragma

Her zaman no-cache.

RateLimit-Limit

Penceredeki istek hakkı.

RateLimit-Remaining

Penceredeki kalan hak.

RateLimit-Reset

Pencerenin sıfırlanmasına kalan saniye.

RateLimit-Policy

Limit politikası; 30;w=60 60 saniyede 30 istek demektir.

application/json

Schema

Schema

access_tokenstringrequired
JWT. Korunan uçlarda Authorization: Bearer <access_token> olarak gönderilir.
Example: eyJhbGciOiJIUzI1NiJ9...
token_typestringrequired
Her zaman Bearer.
Possible values: [Bearer]
expires_inintegerrequired
Access token'ın geçerlilik süresi (saniye).
Example: 86400
refresh_tokenuuidrequired
Token yenilemek için kullanılır.
Example: a170696c-8c1f-4eb5-81bd-391e29fbebc4
scopestringrequired
Token'ın verilen kapsamları, boşlukla ayrılmış. İstenenden farklı olabilir (bkz. Scope).
Example: sms
user_idint64required
Hesap kimliği.
Example: 100001
sub_user_idint64required
Alt kullanıcı kimliği; ana hesapla girişte 0.
Example: 0

Example (auto)

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "a170696c-8c1f-4eb5-81bd-391e29fbebc4",
  "scope": "sms",
  "user_id": 100001,
  "sub_user_id": 0
}

Example

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "a170696c-8c1f-4eb5-81bd-391e29fbebc4",
  "scope": "sms",
  "user_id": 100001,
  "sub_user_id": 0
}

400

invalid_request. İstek işlenemedi.

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [invalid_request]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "invalid_request",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

401

invalid_credentials. Kullanıcı adı veya şifre hatalı.

Response Headers

WWW-Authenticate

Bearer.

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [invalid_credentials]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "invalid_credentials",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

Example

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "invalid_credentials",
  "error": "invalid_grant",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0"
}

403

Hesap kontrollerinden biri geçmedi. code:

Kod	Ne zaman
login_not_permitted	Bu hesapla giriş yapılamıyor.
api_access_denied	Hesabın API erişimi yok.
ip_not_allowed	Bu IP adresinden erişim izni yok.
country_not_allowed	Hesabın yurt dışından erişim izni yok.
account_inactive	Hesap aktif değil.
service_not_activated	İstenen hizmet hesapta aktif değil; denied_scopes ilgili kapsamları listeler.
sub_user_not_permitted	Alt kullanıcının istenen hizmete yetkisi yok; denied_scopes ilgili kapsamları listeler.

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [account_inactive, api_access_denied, country_not_allowed, ip_not_allowed, login_not_permitted, service_not_activated, sub_user_not_permitted]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "account_inactive",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

Example

{
  "type": "urn:problem-type:identity:service-not-activated",
  "title": "Hizmet aktif değil",
  "status": 403,
  "detail": "Hesabınızda istenen hizmet aktif değil.",
  "instance": "/auth/v3/token",
  "code": "service_not_activated",
  "error": "invalid_scope",
  "denied_scopes": [
    "sms:send"
  ],
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0"
}

422

validation_failed. Girdi eksik ya da hatalı; errors her alan için mesajları listeler. Alanlar query string'de gönderildiğinde de bu hata döner.

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [validation_failed]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "validation_failed",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

Example

{
  "type": "urn:problem-type:identity:validation-failed",
  "title": "Doğrulama hatası",
  "status": 422,
  "detail": "Girilen bilgiler eksik veya hatalı.",
  "instance": "/auth/v3/token",
  "code": "validation_failed",
  "error": "invalid_request",
  "errors": {
    "username": [
      "Kullanıcı adı alanı zorunludur."
    ],
    "password": [
      "Şifre alanı zorunludur."
    ]
  },
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0"
}

429

rate_limited: IP başına dakikada 30 istek aşıldı. too_many_failed_attempts: kullanıcı adı + IP başına dakikada 5 hatalı giriş aşıldı.

Response Headers

Retry-After

Tekrar denemeden önce beklenecek süre (saniye).

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [rate_limited, too_many_failed_attempts]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "rate_limited",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

Example

{
  "type": "urn:problem-type:identity:rate-limited",
  "title": "İstek limiti aşıldı",
  "status": 429,
  "detail": "Çok fazla istek gönderildi. Lütfen daha sonra tekrar deneyin.",
  "instance": "/auth/v3/token",
  "code": "rate_limited",
  "error": "temporarily_unavailable",
  "retry_after": 42,
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0"
}

502

service_misconfigured. Sunucu tarafı yapılandırma hatası; kimlik doğrulama servisi isteği şu an işleyemiyor.

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [service_misconfigured]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "service_misconfigured",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

503

service_unavailable. Kimlik doğrulama altyapısına şu an ulaşılamıyor; isteği biraz sonra tekrar gönderebilirsiniz. Servis geçici olarak istek almayı durdurduysa Retry-After beklenecek süreyi verir.

Response Headers

Retry-After

Tekrar denemeden önce beklenecek süre (saniye).

application/problem+json

Schema

Schema

typestringrequired

Hata tipinin URI tanımlayıcısı.

Example: urn:problem-type:identity:invalid-credentials

titlestringrequired

Hata tipinin kısa özeti.

Example: Kimlik doğrulanamadı

statusintegerrequired

HTTP durum kodu.

Example: 401

detailstringrequired

Son kullanıcıya gösterilebilir açıklama (Türkçe).

Example: Kullanıcı adı veya şifre hatalı.

instancestringrequired

İstek yolu.

Example: /auth/v3/token

codestringrequired

Makine tarafından okunabilir kod. İstemci mantığınızı bu alana göre kurmalısınız.

Possible values: [service_unavailable]

request_idstringrequired

Destek talebinde iletilecek istek kimliği; X-Thread-Id yanıt başlığıyla aynıdır.

Example: c7e54ee8-b831-427b-a5a5-af6b66cabbd0

errorstring

OAuth 2.0 hata kodu (RFC 6749 §5.2 / RFC 6750 §3.1), OAuth istemci kütüphaneleri için.

Possible values: [invalid_grant, invalid_token, invalid_scope, access_denied, invalid_request, temporarily_unavailable, server_error]

error_descriptionstring

OAuth 2.0 hata açıklaması (İngilizce).

errors object

Yalnızca 422. Alan adı → mesaj listesi.

property name* string[]

Array [

string

]

denied_scopesstring[]

Yalnızca service_not_activated ve sub_user_not_permitted. Token verilmesini engelleyen kapsamlar.

retry_afterinteger

Yalnızca 429. Tekrar denemeden önce beklenecek süre (saniye).

Example (auto)

{
  "type": "urn:problem-type:identity:invalid-credentials",
  "title": "Kimlik doğrulanamadı",
  "status": 401,
  "detail": "Kullanıcı adı veya şifre hatalı.",
  "instance": "/auth/v3/token",
  "code": "service_unavailable",
  "request_id": "c7e54ee8-b831-427b-a5a5-af6b66cabbd0",
  "error": "invalid_grant",
  "error_description": "string",
  "errors": {},
  "denied_scopes": [
    "string"
  ],
  "retry_after": 0
}

Örnek istek

curl -X POST 'https://ext-api.netgsm.com.tr/auth/v3/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "312XXXXXXX",
  "password": "XXXXXXX",
  "scope": "sms"
}'