Rol, kullanıcıların ve uygulamaların paylaştığı, adı olan bir yetki kümesidir. Her kullanıcının ve her uygulamanın, slug'ıyla başvurulan tam olarak bir rolü vardır. Rollerin kullanıcıya özel yetkilerle birlikte nasıl değerlendirildiği Yetkilendirme sayfasında anlatılır.

Rol nesnesi#

json

{
	"_id": "66f1c0d2a4b5c6d7e8f90131",
	"name": "Support Agent",
	"slug": "support",
	"description": "Can read and edit customers, but not delete them",
	"permissions": [
		"users.read",
		"users.update",
		"user-types.read",
		"roles.read"
	],
	"forbidden": [
		"users.delete"
	],
	"membership_id": "66f1c0d2a4b5c6d7e8f90123",
	"sys": { "created_at": "2026-01-01T12:00:00Z", "created_by": "admin" }
}

Alan	Zorunlu	Açıklama
`name`	evet	Görünen ad.
`slug`	hayır	Membership içinde benzersiz; verilmezse addan türetilir. Kullanıcılar ve uygulamalar role slug'ıyla başvurur.
`description`	hayır
`permissions`	hayır	Rolün izin verdikleri, yetki ifadeleri olarak.
`forbidden`	hayır	Rolün yasakladıkları. Yasak bir girdi, aynı rolün yetkisine karşı her zaman kazanır.

Aynı ifade iki listede birden bulunamaz.

`admin` rolü#

Kurulum, ErtisAuth API'sinin her kaynağı üzerinde create, read, update ve delete yetkisine sahip admin rolünü oluşturur. Slug'ı ayrılmıştır: bu slug'la başka rol oluşturulamaz ve rol silinemez.

Endpoint'ler#

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

Metot	Route	Açıklama	Yetki
`GET`	`/roles/{id}`	Rol getirme (id ya da slug)	`roles.read.{id}`
`GET`	`/roles`	Rolleri listeleme	`roles.read`
`POST`	`/roles/_query`	Rolleri sorgulama	`roles.read`
`GET`	`/roles/search?keyword=`	Rol arama	`roles.read`
`POST`	`/roles`	Rol oluşturma	`roles.create`
`PUT`	`/roles/{id}`	Rol güncelleme	`roles.update.{id}`
`DELETE`	`/roles/{id}`	Rol silme	`roles.delete.{id}`
`DELETE`	`/roles`	Birden fazla rol silme	`roles.delete`
`GET`	`/roles/{id}/check-permission?permission=`	Bir rolün yetkisini kontrol etme	`roles.read`
`GET`	`/roles/check-permission?permission=`	Çağıranın yetkisini kontrol etme	geçerli herhangi bir token

Rol oluşturma#

shell

curl -X POST https://auth.example.com/memberships/<membership_id>/roles \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"name": "Support Agent",
		"slug": "support",
		"permissions": [ "users.read", "users.update", "roles.read" ],
		"forbidden": [ "users.delete" ]
	}'

Yanıt 201 Created: rol.

Hata	Ne zaman
`400 ModelValidationError`	Ad eksik, slug geçersiz ya da aynı ifade iki listede birden var
`400 InvalidRbac`	Bir ifade geçerli değil
`404 MembershipNotFound`	Membership yok
`409 RoleAlreadyExists`	Slug kullanımda
`409 ReservedRole`	Slug `admin`

Rol güncelleme#

http

PUT /memberships/{membershipId}/roles/{id}

Gövde, oluşturma isteğiyle aynı alanlara sahiptir ve rolün permissions ve forbidden listelerini değiştirir. Değişiklik, token'ları yeniden verilmeden, rolü taşıyan her kullanıcıya ve uygulamaya uygulanır. Birden fazla ErtisAuth instance'ı çalıştırıyorsanız her instance rolleri en fazla 5 dakika önbellekte tuttuğundan, değişikliğin hepsine ulaşması bu kadar sürebilir (bkz. Operasyon).

Hiçbir değişiklik içermeyen bir güncelleme 409 IdenticalDocumentError döner.

Rol silme#

http

DELETE /memberships/{membershipId}/roles/{id}

Yanıt 204 No Content. admin rolü silinemez (409 SystemRolesCannotBeDeleted). Birden fazla rol toplu silme ile tek seferde silinebilir.

Not: bir rolü silmeden önce hiçbir kullanıcının ya da uygulamanın onu hâlâ kullanmadığından emin olun: aksi halde istekleri 403 AccessDenied ("role is not found") ile reddedilir.

Yetki kontrolü#

Bkz. Yetkilendirme.

Olaylar#

RoleCreated, RoleUpdated ve RoleDeleted. Bkz. Olaylar.