Kullanıcılar, uygulamalarınıza giriş yapan kişilerdir. Her kullanıcı bir membership'e aittir, bir rolü ve bir kullanıcı tipi vardır ve kendine ait yetkileri olabilir (bkz. Yetkilendirme).

Kullanıcı nesnesi#

json

{
	"_id": "66f1c0d2a4b5c6d7e8f90127",
	"username": "ada",
	"email_address": "ada@example.com",
	"firstname": "Ada",
	"lastname": "Lovelace",
	"role": "support",
	"user_type": "employee",
	"permissions": [ "orders.approve" ],
	"forbidden": [],
	"is_active": true,
	"source_provider": "ErtisAuth",
	"connected_accounts": [],
	"membership_id": "66f1c0d2a4b5c6d7e8f90123",
	"sys": {
		"created_at": "2026-01-01T12:00:00Z",
		"created_by": "admin",
		"modified_at": "2026-01-05T09:12:44Z",
		"modified_by": "ada"
	},
	"department": "Engineering",
	"phone": "+44 20 7946 0000"
}

Standart alanlar yerleşik base-user tipinden gelir; diğer tüm alanları (yukarıdaki department, phone) kullanıcının kullanıcı tipi tanımlar.

Alan	Açıklama
`username`	Zorunlu, membership içinde benzersiz. Girişte kullanılabilir.
`email_address`	Zorunlu, geçerli bir e-posta adresi, membership içinde benzersiz. Girişte kullanılabilir.
`firstname`	Zorunlu.
`lastname`	İsteğe bağlı.
`role`	Zorunlu. Var olan bir rolün slug'ı.
`user_type`	Zorunlu. Abstract olmayan bir kullanıcı tipinin slug'ı (ya da adı); her zaman slug olarak saklanır.
`permissions`, `forbidden`	İsteğe bağlı UBAC girdileri (`resource.action.object`). Bkz. Yetkilendirme.
`is_active`	Kullanıcının giriş yapıp yapamayacağı. Oluşturulurken sunucu tarafından belirlenir (bkz. Aktivasyon).
`source_provider`	Kullanıcının nereden geldiği: `ErtisAuth` ya da kaydolduğu sağlayıcının tipi. Salt okunur.
`connected_accounts`	Kullanıcıya bağlı harici sağlayıcı hesapları. Salt okunur.
`membership_id`	Salt okunur.

Parola hash'i gizli bir alanda saklanır; asla döndürülmez, filtrelenmez ve sıralamada kullanılmaz.

Endpoint'ler#

Tüm route'lar /memberships/{membershipId} altındadır.

Metot	Route	Açıklama	Yetki
`GET`	`/users/{id}`	Kullanıcı getirme	`users.read.{id}`
`GET`	`/users`	Kullanıcıları listeleme	`users.read`
`POST`	`/users/_query`	Kullanıcıları sorgulama	`users.read`
`GET`	`/users/search?keyword=`	Kullanıcı arama	`users.read`
`POST`	`/users`	Kullanıcı oluşturma	`users.create`
`PUT`	`/users/{id}`	Kullanıcı güncelleme	`users.update.{id}`
`DELETE`	`/users/{id}`	Kullanıcı silme	`users.delete.{id}`
`DELETE`	`/users`	Birden fazla kullanıcı silme	`users.delete`
`PUT`	`/users/{id}/change-password`	Parola değiştirme	`users.update.{id}`
`GET`	`/users/check-password?password=`	Çağıranın kendi parolasını kontrol etme	`users.read`
`GET`	`/users/{id}/activate`	Kullanıcıyı etkinleştirme	`users.update.{id}`
`GET`	`/users/{id}/freeze`	Kullanıcıyı dondurma	`users.update.{id}`
`GET`	`/users/activation?uat=`	Aktivasyon token'ıyla etkinleştirme	`users.update`
`POST`	`/users/resend-activation-mail`	Aktivasyon mailini yeniden gönderme	`users.create`
`POST`	`/users/reset-password`	Parola sıfırlamayı başlatma	`users.update`
`GET`	`/users/verify-reset-token?token=`	Sıfırlama token'ını kontrol etme	`users.read`
`POST`	`/users/set-password`	Sıfırlama token'ıyla yeni parola belirleme	`users.update`
`GET`	`/users/{id}/generate-otp`	Tek kullanımlık şifre üretme	`otp.create.{id}`

Aktivasyon, sıfırlama ve OTP endpoint'leri Hesap Kurtarma ve Aktivasyon sayfasında anlatılır.

Bir kullanıcı, ayrıcalıklı alanlar dışında kendi kaydını her zaman güncelleyebilir (kendi kaydı kuralı).

Kullanıcı getirme#

http

GET /memberships/{membershipId}/users/{id}
Authorization: Bearer <access_token>

Yanıt 200 OK: kullanıcı, kullanıcı tipinin özel alanlarıyla birlikte. Kullanıcı yoksa 404 UserNotFound.

Kullanıcıları listeleme, sorgulama ve arama#

http

GET /memberships/{membershipId}/users?skip=0&limit=20&with_count=true&sort=lastname
POST /memberships/{membershipId}/users/_query
GET /memberships/{membershipId}/users/search?keyword=ada

Bkz. API Kuralları. Sorgu endpoint'i, adları bir dilin kurallarına göre sıralamak için locale parametresini de kabul eder (ör. locale=tr). Arama, anahtar kelimeyi büyük/küçük harf ve aksan farkı gözetmeden username, firstname, lastname ve email_address alanlarında arar.

E-posta adresiyle kullanıcı bulma:

shell

curl -X POST 'https://auth.example.com/memberships/<membership_id>/users/_query' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{ "where": { "email_address": "ada@example.com" } }'

Kullanıcı oluşturma#

shell

curl -X POST https://auth.example.com/memberships/<membership_id>/users \
	-H 'Authorization: Bearer <access_token>' \
	-H 'X-Host: https://app.example.com/activate' \
	-H 'Content-Type: application/json' \
	-d '{
		"username": "ada",
		"email_address": "ada@example.com",
		"firstname": "Ada",
		"lastname": "Lovelace",
		"password": "<at least 6 characters>",
		"role": "support",
		"user_type": "employee",
		"department": "Engineering"
	}'

Gövde, miras alınan alanlar dahil user_type şemasına göre doğrulanır. Kullanıcı tipi ek alanlara izin vermiyorsa bilinmeyen alanlar reddedilir.
password zorunludur ve en az 6 karakter olmalıdır. Membership'in algoritmasıyla hash'lenir ve asla düz metin olarak saklanmaz.
Gövdedeki is_active, source_provider ve connected_accounts yok sayılır: membership aktivasyon gerektiriyorsa kullanıcı pasif oluşturulur ve aktivasyon maili X-Host'taki link adresiyle gönderilir; aksi halde kullanıcı hemen aktiftir.
user_type pratikte zorunludur: verilmezse yerleşik base-user tipi kullanılır, o da abstract'tır (400 InheritedTypeIsAbstract).
email_address küçük harfe çevrilerek saklanır.

Yanıt 201 Created: kullanıcı.

Tekrarlanan bir username, e-posta adresi ya da başka bir benzersiz alan, alan hatası olarak bildirilir:

json

{
	"message": "…",
	"errorCode": "ValidationException",
	"statusCode": 400,
	"errors": [
		{
			"message": "The 'email_address' field has unique constraint. The same value is already using in another user.",
			"fieldName": "email_address",
			"fieldPath": "email_address"
		}
	]
}

Hata	Ne zaman
`400 PasswordRequired`, `400 PasswordMinLengthRuleError`	Parola eksik ya da çok kısa
`400 RoleRequired`	`role` eksik
`400 FieldValidationException`, `400 ValidationException`	Bir alan kullanıcı tipi şemasına uymuyor
`400 ValidationException`	Username, e-posta adresi ya da başka bir benzersiz alan başka bir kullanıcı tarafından kullanılıyor (yukarıya bakın)
`404 RoleNotFound`, `404 UserTypeNotFound`	Bilinmeyen rol ya da kullanıcı tipi
`409 UbacsConflicted`	Aynı girdi hem `permissions` hem `forbidden` içinde
`501 NotDefinedAnyMailProvider`, `501 ActivationMailHookWasNotDefined`	Aktivasyon gerekli ama mail gönderilemiyor

Kullanıcı güncelleme#

http

PUT /memberships/{membershipId}/users/{id}

Güncellemeler kısmidir: gönderdiğiniz alanlar mevcut kullanıcıyla birleştirilir, diğerleri değerlerini korur.

shell

curl -X PUT https://auth.example.com/memberships/<membership_id>/users/<user_id> \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{ "lastname": "King", "department": "Research" }'

Birleştirilmiş kullanıcı, kullanıcı tipinin şemasına göre doğrulanır.
Parola burada değiştirilemez; parola değiştirme endpoint'ini kullanın.
role, permissions, forbidden, is_active ya da user_type alanlarını değiştirmek, kullanıcılar kendilerini güncellerken bile, kullanıcı üzerinde gerçek bir users.update yetkisi gerektirir (bkz. Yetkilendirme).
user_type kullanıcı oluşturulduktan sonra değiştirilemez: başka bir tip gönderilirse 400 UserTypeImmutable döner. Bir kullanıcıyı başka bir tipe taşımak için yeni bir kullanıcı oluşturun.

Yanıt 200 OK: güncellenmiş kullanıcı. Hiçbir değişiklik içermeyen bir güncelleme 409 IdenticalDocumentError döner.

Kullanıcı silme#

http

DELETE /memberships/{membershipId}/users/{id}

Yanıt 204 No Content ya da 404 UserNotFound. Birden fazla kullanıcı toplu silme ile tek seferde silinebilir.

Parola değiştirme#

http

PUT /memberships/{membershipId}/users/{id}/change-password
Content-Type: application/json

{ "password": "<new password>" }

Yanıt 200 OK.

Parola değiştikten sonra kullanıcının tüm cihazlardaki oturumu kapatılır: tüm token'ları iptal edilir. Kullanıcılar kendi parolalarını değiştirdiğinde, değişikliği yaptıkları oturum açık kalır. Bu, hesabın ele geçirilmesinin ardından hesabı korur: parolayı değiştirmek saldırganı da dışarı atar.

Kullanıcı kendi parolasını kendi kaydı kuralıyla değiştirebilir; başka birinin parolasını değiştirmek o kullanıcı üzerinde users.update yetkisi gerektirir.

Çağıranın parolasını kontrol etme#

Bir parolanın çağıranın mevcut parolası olup olmadığını sorar; örneğin hassas bir işlemden önce:

http

GET /memberships/{membershipId}/users/check-password?password=<password>
Authorization: Bearer <access_token>

Eşleşirse 200 OK, eşleşmezse 401 döner.

Not: parola query string'de gönderilir; proxy'ler ve sunucular bunu erişim log'larına yazabilir. Altyapınızın bu route için query string'leri loglamadığından emin olun.

Kullanıcıyı etkinleştirme#

http

GET /memberships/{membershipId}/users/{id}/activate

Kullanıcıyı aktivasyon maili olmadan etkinleştirir; örneğin bir yönetici tarafından. Yanıt 200 OK ve kullanıcı; zaten aktifse 400 UserAlreadyActive.

Kullanıcıyı dondurma#

http

GET /memberships/{membershipId}/users/{id}/freeze

Kullanıcıyı pasifleştirir ve tüm token'larını iptal eder: her yerde oturumu kapatılır ve yeniden etkinleştirilene kadar giriş yapamaz. Bekleyen aktivasyon linkleri de çalışmaz hale gelir. Yanıt 200 OK ve kullanıcı; zaten pasifse 400 UserAlreadyInactive.

Not: etkinleştirme ve dondurma, veri değiştiren GET istekleridir. Bunları tarayıcıların ya da crawler'ların önceden yükleyebileceği düz linkler olarak sunmayın.

Olaylar#

Olay	Ne zaman
`UserCreated`	Bir kullanıcı oluşturuldu (sağlayıcıyla kayıt dahil)
`UserUpdated`	Bir kullanıcı güncellendi, etkinleştirildi ya da donduruldu
`UserDeleted`	Bir kullanıcı silindi
`UserPasswordChanged`	Bir parola değiştirildi ya da belirlendi
`UserPasswordReset`	Bir parola sıfırlama başlatıldı

Bkz. Olaylar.