​
Authentication

Hemen Builders API çağrıları Bearer token ile yetkilendirilir. İlk desteklenen OAuth uyumlu akış client_credentials akışıdır ve özellikle private app entegrasyonları için kullanılır.

​
Token endpoint

POST https://dev.hemenmagaza.com/builders/oauth/token
Zorunlu alanlar:
AlanAçıklama
grant_typeŞimdilik sadece client_credentials.
client_idPrivate app için üretilen OAuth client id.
client_secretSadece üretildiği anda görünen client secret.
scopeBoşlukla ayrılmış istenen scope listesi.

​
Token alma örneği

curl -X POST "https://dev.hemenmagaza.com/builders/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "products:read orders:read"
  }'
Response: 
{
  "access_token": "hm_token",
  "token_type": "Bearer",
  "expires_in": 0,
  "scope": "products:read orders:read"
}

​
Bearer header

Token aldıktan sonra API isteklerinde kullanın: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

​
Scope kontrolü

Token isteğinde gönderilen scope listesi app’in approved_scopes alanının dışına çıkamaz. App’e onaylanmamış scope istenirse token verilmez. Örnek hata: 
{
  "error": "invalid_scope",
  "error_description": "Requested scope is not approved for this app."
}

​
Secret güvenliği

Client secret için kurallar:
  • Düz metin saklanmaz.
  • Hash ve son dört karakter tutulur.
  • Kaybedilirse geri okunamaz.
  • Rotate edildiğinde eski secret geçersiz kabul edilir.
  • Secret frontend bundle içine yazılmamalıdır.

​
Rotate ve revoke

Tenant admin panelinden:
  • Client secret rotate edilebilir.
  • Private app token üretilebilir.
  • Kullanılmayan token revoke edilebilir.
  • Scope değiştirildiğinde aktif credential’ların yeniden yetkilendirilmesi gerekir.

​
Hata kodları

KodDurum
400 unsupported_grant_typegrant_type desteklenmiyor.
400 invalid_requestclient_id veya client_secret eksik.
400 invalid_scopeİstenen scope app için onaylı değil.
401 invalid_clientClient credential hatalı veya app aktif değil.
401 unauthenticatedBearer token eksik veya geçersiz.
403 scope deniedToken geçerli ama işlem için gerekli scope yok.

​
Production önerileri

  • Her entegrasyon için ayrı app ve credential kullanın.
  • Gereksiz scope vermeyin.
  • Secret değerlerini .env, CI secret store veya vault içinde tutun.
  • Token ve secret değerlerini loglamayın.
  • Webhook ve admin action imzalarını ayrıca doğrulayın.