Uygulama, ErtisAuth'un bir makine istemcisidir: bir backend servisi, bir worker, sunucu taraflı bir web uygulaması. Uygulamalar giriş yapmaz; her istekte bir Basic token gönderir:

http

Authorization: Basic <application_id>:<secret>

Kullanıcılar gibi uygulamaların da bir rolü vardır ve kendilerine ait yetkileri (permissions, forbidden) olabilir; bunlar Yetkilendirme sayfasında anlatıldığı gibi değerlendirilir.

Tipik kullanımlar:

ürününüz adına kullanıcıları yöneten bir backend (kayıt, profil sayfaları, yönetim ekranları),
parola sıfırlama ve aktivasyon sayfalarınızın, ErtisAuth'u uygulamanın token'ıyla çağıran sunucu tarafı,
SDK ile korunan ve birbirini çağıran servisler.

Uygulama nesnesi#

json

{
	"_id": "66f1c0d2a4b5c6d7e8f90126",
	"name": "Backend",
	"slug": "backend",
	"role": "backend-service",
	"permissions": [ "users.create" ],
	"forbidden": [],
	"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.
`role`	evet	Var olan bir rolün slug'ı.
`permissions`, `forbidden`	hayır	Uygulamanın UBAC girdileri (`resource.action.object`).

Secret hiçbir zaman uygulama nesnesinin parçası değildir.

Secret#

Secret, uygulama oluşturulurken üretilir ve yalnızca o yanıtta döndürülür.
ErtisAuth yalnızca hash'ini saklar. Yöneticiler dahil hiç kimse onu geri okuyamaz.
Süresi dolmaz. Sızmış olabileceğinde ya da rutin olarak secret yenileme ile değiştirin.

Secret'ı bir parola gibi saklayın: bir secret store'da ya da bir ortam değişkeninde; asla kaynak kontrolünde ya da tarayıcıda değil.

Endpoint'ler#

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

Metot	Route	Açıklama	Yetki
`GET`	`/applications/{id}`	Uygulama getirme (id ya da slug)	`applications.read.{id}`
`GET`	`/applications`	Uygulamaları listeleme	`applications.read`
`POST`	`/applications/_query`	Uygulamaları sorgulama	`applications.read`
`GET`	`/applications/search?keyword=`	Uygulama arama	`applications.read`
`POST`	`/applications`	Uygulama oluşturma	`applications.create`
`PUT`	`/applications/{id}`	Uygulama güncelleme	`applications.update.{id}`
`POST`	`/applications/{id}/secret`	Secret yenileme	`applications.update.{id}`
`DELETE`	`/applications/{id}`	Uygulama silme	`applications.delete.{id}`
`DELETE`	`/applications`	Birden fazla uygulama silme	`applications.delete`

Bir uygulama, rolü yasaklamadıkça kendi kaydını her zaman okuyabilir ve güncelleyebilir.

Uygulama oluşturma#

shell

curl -X POST https://auth.example.com/memberships/<membership_id>/applications \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"name": "Billing Service",
		"role": "billing"
	}'

Yanıt 201 Created

json

{
	"_id": "66f1c0d2a4b5c6d7e8f90140",
	"name": "Billing Service",
	"slug": "billing-service",
	"role": "billing",
	"membership_id": "66f1c0d2a4b5c6d7e8f90123",
	"secret": "<application_secret>",
	"sys": { "created_at": "2026-01-01T12:00:00Z", "created_by": "admin" }
}

secret'ı şimdi kaydedin: bir daha okunamaz.

Hata	Ne zaman
`400 ModelValidationError`	Ad ya da rol eksik, bilinmeyen rol, geçersiz slug ya da aynı ifade iki listede birden var
`404 MembershipNotFound`	Membership yok
`409 ApplicationAlreadyExists`	Slug kullanımda

Uygulama güncelleme#

http

PUT /memberships/{membershipId}/applications/{id}

name, slug, role, permissions ve forbidden alanlarını günceller. Secret burada değiştirilmez. Hiçbir değişiklik içermeyen bir güncelleme 409 IdenticalDocumentError döner.

Secret yenileme#

http

POST /memberships/{membershipId}/applications/{id}/secret
Authorization: Bearer <access_token>

Yanıt 200 OK: yeni secret'ıyla birlikte uygulama.

Uyarı: eski secret hemen çalışmaz hale gelir. Yeni secret'ı uygulamaya hemen dağıtın; Basic token'ları SDK üzerinden önbelleğe alan servisler eskisini BasicTokenCacheTTL süreleri boyunca kabul etmeye devam edebilir.

Uygulama silme#

http

DELETE /memberships/{membershipId}/applications/{id}

Yanıt 204 No Content. Uygulamanın Basic token'ı çalışmaz hale gelir.

Basic token'ı kullanma#

shell

curl https://auth.example.com/memberships/<membership_id>/users?limit=10 \
	-H 'Authorization: Basic 66f1c0d2a4b5c6d7e8f90140:<application_secret>'

Token, düz metin olarak id:secret biçimindedir; base64 ile kodlanmaz.
Basic token'la GET /me uygulamayı döner.
Bilinmeyen bir uygulama, yanlış bir secret ve bilinmeyen bir membership'in hepsi 401 InvalidToken ile yanıtlanır.

Eski uygulamaları taşıma#

Uygulamaya özel secret'lardan önce oluşturulan uygulamalar, secret olarak membership'in secret key'iyle kimlik doğruluyordu. Bir geçiş sırasında çalışmaya devam etmeleri için membership, henüz kendi secret'ı olmayan uygulamalar için membership secret'ını geçici olarak kabul edebilir:

json

{ "allow_membership_secret_for_applications": true }

Bu alan membership güncelleme isteğinin parçasıdır. Her uygulamayı secret'ını yenileyip yenisini dağıtarak taşıyın; o andan itibaren yalnızca kendi secret'ı çalışır. Tüm uygulamalar taşındığında anahtarı false yapın.

Not: bu anahtar geçicidir ve gelecekteki bir sürümde kaldırılacaktır. Yeni membership'lerde kapalıdır.

Olaylar#

ApplicationCreated, ApplicationUpdated ve ApplicationDeleted. Bkz. Olaylar.