API Kuralları

Bu sayfadaki kurallar ErtisAuth API'sinin her endpoint'i için geçerlidir.

Temel URL ve route'lar#

Bu dokümantasyondaki tüm örnekler temel URL olarak https://auth.example.com kullanır. ErtisAuth route'larını host'un kökünden sunar; onu bir yol öneki altında yayınlıyorsanız (örneğin bir gateway arkasında /api/v1), bu öneki her route'a ekleyin.

Route'lar üç gruba ayrılır:

Membership izolasyonu#

Membership'e bağlı bir route'a yapılan istek, aynı membership'e ait bir token ile yapılmalıdır. Başka bir membership'in geçerli bir token'ı, yetkileri ne olursa olsun 403 AccessDenied ile reddedilir.

Header'lar#

İstek ve yanıt gövdeleri#

• Gövdeler JSON'dır. Alan adları çoğu kaynakta snake_case'dir (email_address, expires_in); sağlayıcılar, mail hook'lar ve kullanıcı tiplerinin bayrakları camelCase kullanır (defaultRole, mailSubject, isAbstract). Her referans sayfası tam alan adlarını gösterir.
• Tarihler UTC cinsinden ISO 8601 dizeleridir.
• İstemci kabul ediyorsa yanıtlar Brotli ya da Gzip ile sıkıştırılır.

Durum kodları#

Hatalar#

Hataların ortak bir biçimi vardır:

{
	"message": "User not found in db by given _id: <66f1c0d2a4b5c6d7e8f90124>",
	"errorCode": "UserNotFound",
	"statusCode": 404
}

Kodunuzda errorCode alanını kullanın; message insanlar içindir ve değişebilir. Tüm kodlar Hata Kodları sayfasında listelenir.

Doğrulama hataları sorunların listesini data alanında taşır:

{
	"message": "Some fields are not validated, invalid or missing. Check response detail.",
	"errorCode": "ModelValidationError",
	"statusCode": 400,
	"data": [ "Expires-in is required", "Secret key is required" ]
}

Bir kullanıcının kullanıcı tipi şemasıyla doğrulanan özel alanlarındaki hatalar alanın adını verir:

{
	"message": "String length can not be greater than 20",
	"fieldName": "phone",
	"fieldPath": "phone",
	"errorCode": "FieldValidationException",
	"statusCode": 400
}

Aynı anda birden fazla alan geçersizse hepsi raporlanır:

{
	"message": "…",
	"errorCode": "ValidationException",
	"statusCode": 400,
	"errors": [
		{ "message": "phone is required", "fieldName": "phone", "fieldPath": "phone" },
		{ "message": "String length can not be less than 2", "fieldName": "firstname", "fieldPath": "firstname" }
	]
}

Geçerli bir ObjectId olmayan bir id 400 ParameterFormatError döner.

Kaynakları listeleme#

Liste endpoint'leri (GET /memberships/{membershipId}/users ve benzerleri) query parametreleriyle sayfalanabilir ve sıralanabilir:

curl 'https://auth.example.com/memberships/<membership_id>/users?skip=0&limit=2&with_count=true&sort=sys.created_at%20desc' \
	-H 'Authorization: Bearer <access_token>'

{
	"count": 1250,
	"items": [
		{ "_id": "…", "username": "jane", "…": "…" },
		{ "_id": "…", "username": "john", "…": "…" }
	]
}

with_count=true olmadan count hesaplanmaz.

Kaynakları sorgulama#

Kaynakların çoğunda, where alanında bir MongoDB sorgusu, select alanında isteğe bağlı bir projeksiyon alan bir POST …/_query endpoint'i vardır:

curl -X POST 'https://auth.example.com/memberships/<membership_id>/users/_query?limit=50&sort=lastname' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"where": {
			"user_type": "customer",
			"is_active": true,
			"sys.created_at": { "$gte": "2026-01-01T00:00:00Z" }
		},
		"select": {
			"username": 1,
			"email_address": 1,
			"firstname": 1
		}
	}'

• Liste endpoint'lerinin sayfalama ve sıralama parametreleri burada da geçerlidir.
• select, alanları 1 ya da true ile dahil eder, 0 ya da false ile dışarıda bırakır.
• Membership filtresi her zaman sunucu tarafından eklenir: bir sorgu başka bir membership'in verisini asla okuyamaz.
• JavaScript operatörleri ($where, $function, $accumulator) 400 InvalidQuery ile reddedilir.
• password_hash gibi gizli alanlar ne döndürülebilir ne de filtrelerde ya da sıralamada kullanılabilir.
• Kullanıcılarda isteğe bağlı locale query parametresi (ör. locale=tr) sıralamanın collation'ını belirler; böylece adlar o dilde doğru sıralanır.

Aggregation#

Aktif token'lar ayrıca, JSON dizisi olarak aggregation pipeline aşamaları alan POST …/active-tokens/_aggregate endpoint'ini destekler. Membership filtresi sunucu tarafından ilk aşama olarak eklenir.

Yalnızca pipeline'dan geçen dokümanları dönüştüren aşamalara izin verilir: $match, $project, $addFields, $set, $unset, $group, $sort, $limit, $skip, $count, $unwind, $bucket, $bucketAuto, $sortByCount, $replaceRoot, $replaceWith, $sample, $setWindowFields ve $facet. Diğer tüm aşamalar, özellikle başka koleksiyonları okuyan ya da onlara yazanlar ($lookup, $graphLookup, $unionWith, $out, $merge), 400 UnsupportedAggregationStage ile reddedilir.

curl -X POST 'https://auth.example.com/memberships/<membership_id>/active-tokens/_aggregate' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '[
		{ "$group": { "_id": "$user_id", "sessions": { "$sum": 1 } } },
		{ "$sort": { "sessions": -1 } },
		{ "$limit": 10 }
	]'

Kaynaklarda arama#

Kullanıcılar, roller, uygulamalar ve membership'lerde tam metin arama vardır:

curl 'https://auth.example.com/memberships/<membership_id>/users/search?keyword=lovelace&limit=10' \
	-H 'Authorization: Bearer <access_token>'

keyword zorunludur (aksi halde 400 SearchKeywordRequired). Sayfalama ve sıralama liste endpoint'lerindeki gibi çalışır.

Oluşturma ve güncelleme#

• POST bir kaynak oluşturur ve kaynakla birlikte bir Location header'ı içeren 201 Created döner.
• PUT /{id} bir kaynağı günceller. Id her zaman route'tan gelir; gövdedeki bir _id yok sayılır.
• Hiçbir şeyi değiştirmeyen bir güncelleme 409 IdenticalDocumentError döner. İstemciniz değişmemiş veri gönderebiliyorsa bunu başarı olarak değerlendirin.
• Gövdede gönderilen bir sys nesnesi yok sayılır.

Toplu silme#

Kullanıcılar, roller, uygulamalar, webhook'lar, mail hook'lar ve kod politikaları, koleksiyon route'una gövdesinde id'lerden oluşan bir JSON dizisi bulunan bir DELETE isteğiyle toplu olarak silinebilir:

curl -X DELETE 'https://auth.example.com/memberships/<membership_id>/users' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '[ "66f1c0d2a4b5c6d7e8f90124", "66f1c0d2a4b5c6d7e8f90127" ]'