Geliştirme dokümantasyonu

Bu belgeler Keydra'nın geliştirilmekte olan hâlini anlatır; yayımlanmış bir sürüm değildir. Anlatılanlar bir sürüm çıkana kadar değişebilir.

API referansı

/api/v1 altında REST, yanında GraphQL. İkisi de aynı servisleri aynı izinlerle çağırır; ayrıca soketler ve akışlar.

İki yüzey ve hangisi ne için#

Keydra iki ayrı yüzeyde yanıt verir. Bunlar tek bir yapının iki yarısı değildir.

/graphql üzerinde GraphQL: 135 işlem bulunur. Keydra arayüzünün kullandığı yüzey budur. Bağlantı kataloğu, anahtar tarayıcının ağacı ve değişiklik işlemleri, izleme, göç işleri, zamanlanmış işler, uyarılar, yedekler, tüneller, erişim denetimi, denetim günlüğü, oturumlar — hemen bütün sayfalar sorularını buraya sorar.
/api/v1 altında REST: 161 uç nokta bulunur. Eksiksiz yüzeydir ve bir betiği ya da başka bir aracı bu yüzeye göre yazarsınız. Sürüm numarası yolun içindedir; bu da iç bir sorgunun veremeyeceği bir kararlılık sözü verir.

İkisi de aynı servisleri çağırır ve aynı yapıları döndürür: GraphQL tipleri, REST uç noktasının zaten döndürdüğü DTO’lardır. İkisinin bir alanın adı konusunda ayrışmasını engelleyen de budur. Her iki yüzeydeki her işlem aynı izin denetiminden geçer; doğrudan veritabanına uzanan bir çözücü, aynı eve açılan ikinci bir kapı olurdu.

Arayüz neden GraphQL’e taşındı#

Üç ayrı veriye ihtiyaç duyan bir sayfa üç istek yapıyordu; uzun bir listenin altı sütununu gösteren bir sayfa ise her satırın tamamını indiriyordu. /api/v1/migrations 31 KB, /api/v1/schedules/runs 22 KB yanıt döndürür; altı sütun gösteren bir tablo bunun belki onda birini kullanır.

Sayfalar tek tek ve bütün hâlinde taşındı. Yarısı bir yüzeyde, yarısı diğerinde kalan bir sayfa iki ayrı önbellek anlamına gelirdi. REST uç noktaları, onları çağıran hiçbir şey kalmayana kadar yerinde durur; aşağıdaki listenin arayüzün kullandığından uzun olmasının nedeni budur.

Arayüzün hâlâ REST kullandığı yerler#

Bunların çoğu artık kullanılmayan kalıntılar değil, GraphQL’in uygun olmadığı işlerdir:

Dosyalar: Anahtarları dışa ve içe aktarma. Dosya bir alan değildir.
Değerler: Anahtar içeriğini okuma ve yazma, kodlama listesini alma.
Oturum açma: Form gönderimi, çıkış, ilk kurulum, sağlayıcı yönlendirmesi, davet ve parola sıfırlama sayfaları. Bunlar, soru sorulacak bir oturum daha oluşmadan çalışır.
/api/v1/about: Bir kez okunan küçük bir kayıt.
Soketler: Bildirim hattı, konsol ve komut izleme. Her biri dinleyene belirli türde olay taşır; sayfa başına ayrı abonelik açmak, aynı bilgiyi tekrarlayan ikinci bir soket olurdu.

Kimlik doğrulama#

Her iki yüzey de arayüzün zaten taşıdığı oturum çereziyle doğrulanır. Ayrı bir API belirteci mekanizması yoktur: betik de bir kullanıcı olarak çalışır ve o kullanıcı oturum açar.

GraphQL GET isteklerini reddeder. Adres satırındaki bir sorgu; vekil günlüğüne, tarayıcı geçmişine ve yönlendiren başlığına da yazılır. Keydra sorguları ise bağlantı kimlikleri ve anahtar desenleri içerir.

İç gözlem ve şema belgesi geliştirmede açık, üretimde kapalıdır. Hiçbiri tek başına açık değildir — kimliği doğrulanmış bir çağıran her iki durumda da erişebildiğine erişir — ama şema, bütün alanların ve argümanların haritasıdır; üretim kurulumunda bu haritaya ihtiyaç duyan kimse yoktur.

OpenAPI#

Çalışan bir Keydra kendi OpenAPI belgesini yayımlar:

bash

curl -s http://localhost:8181/api/openapi > keydra-openapi.yaml

Geliştirme profilinde /q/swagger-ui adresinden belgeye etkileşimli olarak göz atabilirsiniz.

Bu belge yetkili şemadır: istek ve yanıt yapıları, durum kodları ve doğrulama kuralları onları sunan koddan üretilir. Aşağıdaki tablolar uç noktaları ve gerektirdikleri izinleri gösterir; alanların ayrıntısı belgede bulunur.

GraphQL şeması geliştirmede /graphql/schema.graphql adresinde sunulur ve iç gözlem de orada açıktır. Üretimde ikisi de kapalıdır.

WebSocket’ler ve akışlar#

Yol Açıklama

Yol	Açıklama
`/api/v1/connections/{connectionId}/commands`	Hedefin kendi MONITOR akışı; sırlar motordan çıkmadan önce maskelenir. İstenene kadar kapalıdır, çünkü açıkken sunucuya iş çıkarır.
`/api/v1/connections/{connectionId}/console`	Tek bir hedefe karşı bir komut konsolu oturumu. Türlü sonuçlar geldikçe akıtılır.
`/api/v1/notifications`	Bildirim hattı. Bütün arayüz için tek soket; her sunucu tarafı değişikliği bir kategori, bir yük ve bir zaman damgasından oluşan zarf olarak taşır. Tek bir hedefe dair yayın, yalnızca sahibinin o hedefi görebildiği soketlere ulaşır.

/api/v1/connections/{connectionId}/commands

Hedefin kendi MONITOR akışı; sırlar motordan çıkmadan önce maskelenir. İstenene kadar kapalıdır, çünkü açıkken sunucuya iş çıkarır.

/api/v1/connections/{connectionId}/console

Tek bir hedefe karşı bir komut konsolu oturumu. Türlü sonuçlar geldikçe akıtılır.

/api/v1/notifications

Bildirim hattı. Bütün arayüz için tek soket; her sunucu tarafı değişikliği bir kategori, bir yük ve bir zaman damgasından oluşan zarf olarak taşır. Tek bir hedefe dair yayın, yalnızca sahibinin o hedefi görebildiği soketlere ulaşır.

Bildirim zarfı#

Bildirim hattındaki bütün mesajlar aynı yapıdadır:

json

{
  "category": "ConnectionStatusChanged",
  "payload": { },
  "ts": "2026-01-01T00:00:00Z"
}

Tek bir hedefe ait bir yayın, yalnızca sahibinin o hedefi görebildiği soketlere ulaşır.

Kategori Açıklama

Kategori	Açıklama
`ConnectionCreated`	Bağlantı profili eklendi.
`ConnectionUpdated`	Bağlantı profili değişti. Havuzdaki istemcileri ve tüneli kapatılır; profil artık başka bir sunucuyu gösteriyor olabilir.
`ConnectionDeleted`	Bağlantı profili kaldırıldı.
`ConnectionStatusChanged`	Hedef ayağa kalktı, düştü ya da farklı bir türev veya sürüm bildirdi.
`KeysChanged`	Hedefteki anahtarlar oluşturuldu, yeniden adlandırıldı, süre aldı ya da silindi.
`ValueChanged`	Anahtarın içeriği değişti.
`ChannelMessage`	Abone olunan kanala mesaj geldi.
`SubscriptionChanged`	Abonelik açıldı, kapandı ya da bağlantısı düştüğü için sona erdi.
`MetricsSample`	İzlenen hedeften yeni bir ölçüm geldi.
`MonitoringChanged`	Hedef için örnekleme başladı ya da durdu.
`MigrationProgress`	İki hedef arasındaki göç işinin ilerlemesi. İşi başlatan isteğe yanıt olarak değil, yayın olarak gönderilir; böylece yarısında yenilenen bir sayfa süren işi gözden kaybetmez.
`ScheduleFailed`	Zamanlanmış iş, planlandığı işi yapamadı. Yalnızca başarısızlıklar bildirilir: beş dakikada bir gelen başarı bildirimi, asıl önemli olanı gözden kaçırtırdı.
`ScheduleRan`	Zamanlanmış iş sonuçtan bağımsız olarak tamamlandı. "Son çalışma" sütunu çizen tablolar için gerekir; o sütun başarıda da başarısızlıkta da değişmelidir.
`AlertChanged`	Uyarı kuralı sessiz, beklemede ve tetikte durumları arasında geçiş yaptı. Yalnızca geçişler bildirilir; altı saattir tetikte olan kural tek bir mesaj gönderir.
`SessionEnded`	Oturum burada ya da başka bir örnekte sonlandırıldı. Onu taşıyan tarayıcı bir sonraki isteğinde çalışmayı bırakır.
`SignInFlagged`	Başarılı bir giriş, kendisinden öncekilere benzemiyordu.
`PurgeProgress`	Toplu silmenin nereye geldiği. Glob ile silme, anahtar uzayını gruplar hâlinde yürür; bu yüzden sonunda tek bir yanıt vermek yerine ilerledikçe bildirir — dört dakika boyunca hiçbir şey göstermeyen bir sayfa, durmuş bir sayfadan ayırt edilemezdi.
`ApprovalRequested`	Birisi, ikinci bir kişiyi bekleyen bir hedefte işlem istedi. İçinde yalnızca isteğin kimliği ve hedef vardır, başka bir şey değil: yayının izleyicisi o hedefi görebilen herkestir ve bu küme, isteği yanıtlayabilecek kişilerden geniştir.
`ApprovalChanged`	Bir istek onaylandı, reddedildi, geri çekildi, süresi doldu ya da çalışmasını bitirdi. Kimsenin düğmeye basmadığı bitişler de dâhil her bitiş bildirilir; çünkü yanıtı bekleyen kişi, onun geldiğini görmeye en çok ihtiyaç duyan kişidir.

ConnectionCreated

Bağlantı profili eklendi.

ConnectionUpdated

Bağlantı profili değişti. Havuzdaki istemcileri ve tüneli kapatılır; profil artık başka bir sunucuyu gösteriyor olabilir.

ConnectionDeleted

Bağlantı profili kaldırıldı.

ConnectionStatusChanged

Hedef ayağa kalktı, düştü ya da farklı bir türev veya sürüm bildirdi.

KeysChanged

Hedefteki anahtarlar oluşturuldu, yeniden adlandırıldı, süre aldı ya da silindi.

ValueChanged

Anahtarın içeriği değişti.

ChannelMessage

Abone olunan kanala mesaj geldi.

SubscriptionChanged

Abonelik açıldı, kapandı ya da bağlantısı düştüğü için sona erdi.

MetricsSample

İzlenen hedeften yeni bir ölçüm geldi.

MonitoringChanged

Hedef için örnekleme başladı ya da durdu.

MigrationProgress

İki hedef arasındaki göç işinin ilerlemesi. İşi başlatan isteğe yanıt olarak değil, yayın olarak gönderilir; böylece yarısında yenilenen bir sayfa süren işi gözden kaybetmez.

ScheduleFailed

Zamanlanmış iş, planlandığı işi yapamadı. Yalnızca başarısızlıklar bildirilir: beş dakikada bir gelen başarı bildirimi, asıl önemli olanı gözden kaçırtırdı.

ScheduleRan

Zamanlanmış iş sonuçtan bağımsız olarak tamamlandı. "Son çalışma" sütunu çizen tablolar için gerekir; o sütun başarıda da başarısızlıkta da değişmelidir.

AlertChanged

Uyarı kuralı sessiz, beklemede ve tetikte durumları arasında geçiş yaptı. Yalnızca geçişler bildirilir; altı saattir tetikte olan kural tek bir mesaj gönderir.

SessionEnded

Oturum burada ya da başka bir örnekte sonlandırıldı. Onu taşıyan tarayıcı bir sonraki isteğinde çalışmayı bırakır.

SignInFlagged

Başarılı bir giriş, kendisinden öncekilere benzemiyordu.

PurgeProgress

Toplu silmenin nereye geldiği. Glob ile silme, anahtar uzayını gruplar hâlinde yürür; bu yüzden sonunda tek bir yanıt vermek yerine ilerledikçe bildirir — dört dakika boyunca hiçbir şey göstermeyen bir sayfa, durmuş bir sayfadan ayırt edilemezdi.

ApprovalRequested

Birisi, ikinci bir kişiyi bekleyen bir hedefte işlem istedi. İçinde yalnızca isteğin kimliği ve hedef vardır, başka bir şey değil: yayının izleyicisi o hedefi görebilen herkestir ve bu küme, isteği yanıtlayabilecek kişilerden geniştir.

ApprovalChanged

Bir istek onaylandı, reddedildi, geri çekildi, süresi doldu ya da çalışmasını bitirdi. Kimsenin düğmeye basmadığı bitişler de dâhil her bitiş bildirilir; çünkü yanıtı bekleyen kişi, onun geldiğini görmeye en çok ihtiyaç duyan kişidir.

Server-Sent Events#

Anahtar sayımı, yanıtın tamamı hazırlanmadan Server-Sent Events olarak akıtılır; böylece arayüz SCAN sürerken ilk anahtarları çizer. Yanındaki GraphQL aboneliği ise yalnızca çağıranın istediği alanları gönderir: yalnızca ad ve tür gösteren bir tarayıcıya, bir milyon anahtarlık veritabanındaki her anahtarın TTL’i ve boyutu değil, yalnızca ad ve tür gider.

REST uç noktaları#

Uç noktalar, kaynakların taşıdığı etikete göre gruplanmıştır. Gereken sütunu, uç noktanın denetlediği izni gösterir; denetim yalnızca kaba bir role dayanıyorsa rol adı yazılır.

Liste, arayüzün artık çağırmadığı uç noktaları da içerir. Bunlar, onları çağıran hiçbir şey kalmayana kadar yerinde durur: son çağıran taşındığı gün bir uç noktayı silmek, kimsenin hatırlamadığı bir istemciyi bozmanın en kolay yoludur.

About
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/about`	Oturum açmış olmak	Get application name, version and build metadata

Alert deliveries
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/alert-deliveries`	`admin`	Every configured delivery, and how many rules use it
`POST`	`/api/v1/alert-deliveries`	`admin`	Add somewhere to send alerts
`DELETE`	`/api/v1/alert-deliveries/{id}`	`admin`	Remove a delivery
`PUT`	`/api/v1/alert-deliveries/{id}`	`admin`	Change a delivery
`POST`	`/api/v1/alert-deliveries/{id}/check`	`admin`	Send a test message
`GET`	`/api/v1/alert-deliveries/instance-notices`	`admin`	Which destinations hear about Keydra itself
`PUT`	`/api/v1/alert-deliveries/instance-notices`	`admin`	Choose which destinations hear about Keydra itself

Alerts
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/alerts`	`viewer`, `operator`, `admin`	Every rule, with where it currently stands
`POST`	`/api/v1/alerts`	`alert:manage`	Watch for a condition
`DELETE`	`/api/v1/alerts/{id}`	`alert:manage`	Remove a rule, and the record of what it said
`PUT`	`/api/v1/alerts/{id}`	`alert:manage`	Change a rule
`GET`	`/api/v1/alerts/events`	`viewer`, `operator`, `admin`	What the rules have said
`GET`	`/api/v1/alerts/metrics`	`viewer`, `operator`, `admin`	The metrics a rule can watch

Analysis
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/analysis/keyspace`	`analysis:read`	Where this target’s memory went

Approvals
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/approvals`	`operator`, `admin`	Operations waiting for a second person
`DELETE`	`/api/v1/approvals/{id}`	`operator`, `admin`	Withdraw a request you made
`GET`	`/api/v1/approvals/{id}`	`operator`, `admin`	One request, with what it would do
`POST`	`/api/v1/approvals/{id}/approve`	`operator`, `admin`	Agree to an operation, which starts it
`POST`	`/api/v1/approvals/{id}/decline`	`operator`, `admin`	Say no, and say why

Authentication
Yöntem	Yol	Gereken	Ne yapar
`POST`	`/api/v1/auth/logout`	Oturum açmış olmak	End this session
`GET`	`/api/v1/auth/permissions`	Oturum açmış olmak	What the caller may do, per target
`POST`	`/api/v1/auth/setup`	Oturum açmış olmak	Create the first administrator
`GET`	`/api/v1/auth/state`	Oturum açmış olmak	Whether there is anything to sign into, and whether anybody has

Backup destinations
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/backup-destinations`	`admin`	Every configured destination
`POST`	`/api/v1/backup-destinations`	`admin`	Add a destination
`DELETE`	`/api/v1/backup-destinations/{id}`	`admin`	Remove a destination
`PUT`	`/api/v1/backup-destinations/{id}`	`admin`	Change a destination
`POST`	`/api/v1/backup-destinations/{id}/check`	`admin`	Find out whether it works
`POST`	`/api/v1/backup-destinations/check`	`admin`	Try a destination that has not been saved
`POST`	`/api/v1/backup-destinations/keys`	`admin`	Generate a key pair for encrypting backups

Connections
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections`	Oturum açmış olmak	List all connection profiles with their last known status
`POST`	`/api/v1/connections`	`connection:create`	Create a connection profile
`DELETE`	`/api/v1/connections/{id}`	`connection:delete`	Delete a connection profile
`GET`	`/api/v1/connections/{id}`	`connection:view`	Get one connection profile
`PUT`	`/api/v1/connections/{id}`	`connection:edit`	Update a connection profile
`POST`	`/api/v1/connections/{id}/test`	`connection:view`	Probe a saved profile and record the result
`POST`	`/api/v1/connections/test`	`connection:create`	Probe a profile that has not been saved

Console
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/console/denied-commands`	`console:run`	Commands the console refuses to run on this target
`DELETE`	`/api/v1/connections/{connectionId}/console/history`	`console:run`	Forget your own command history on this target
`GET`	`/api/v1/connections/{connectionId}/console/history`	`console:run`	Command lines you have previously run against this target

Databases
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/databases`	Oturum açmış olmak	The databases this target holds

Encryption
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/security/encryption`	`admin`	Which key the stored secrets are under
`POST`	`/api/v1/security/encryption/rotate`	`admin`	Re-encrypt everything with the key that writes now

Grants
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/authz/grants`	`admin`	Every grant, with names beside the ids
`POST`	`/api/v1/authz/grants`	`admin`	Grant a role on a scope
`DELETE`	`/api/v1/authz/grants/{id}`	`admin`	Take a grant back

Groups
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/authz/groups`	`admin`	Every group, with what is directly inside it
`POST`	`/api/v1/authz/groups`	`admin`	Create a group
`DELETE`	`/api/v1/authz/groups/{id}`	`admin`	Remove a group
`POST`	`/api/v1/authz/groups/{id}/members`	`admin`	Put a person, or another group, into this group
`DELETE`	`/api/v1/authz/groups/members/{membershipId}`	`admin`	Take something out of a group

Identity providers
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/authz/providers`	`admin`	Every configured provider
`POST`	`/api/v1/authz/providers`	`admin`	Add a provider
`DELETE`	`/api/v1/authz/providers/{id}`	`admin`	Remove a provider
`PUT`	`/api/v1/authz/providers/{id}`	`admin`	Change a provider
`POST`	`/api/v1/authz/providers/{id}/group-mappings`	`admin`	Map a claim value to a Keydra group
`DELETE`	`/api/v1/authz/providers/group-mappings/{mappingId}`	`admin`	Remove a mapping

Instances
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/instances`	`instance:read`	Who is running and what they depend on
`DELETE`	`/api/v1/instances/{id}/drain`	`instance:drain`	Put an instance back into service
`POST`	`/api/v1/instances/{id}/drain`	`instance:drain`	Take an instance out of service
`POST`	`/api/v1/instances/reachability`	`instance:read`	Ask everything Keydra reaches whether it is there, now
`GET`	`/api/v1/instances/reachability/history`	`instance:read`	When things Keydra reaches started and stopped answering
`GET`	`/api/v1/instances/roster`	`instance:read`	Who is running, and what each of them is holding

Invitations
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/invitations/{token}`	Herkese açık	Whether a link can still be used
`POST`	`/api/v1/invitations/{token}`	Herkese açık	Set a password with a link
`POST`	`/api/v1/invitations/for-user/{id}`	`users:manage`	Send somebody a link to set their own password
`POST`	`/api/v1/invitations/forgotten`	Herkese açık	Ask for a link because a password has been forgotten

Keys
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/keys`	`keys:read`	Stream keys matching a filter
`POST`	`/api/v1/connections/{connectionId}/keys/copy`	`keys:write`	Copy a key to a new name
`POST`	`/api/v1/connections/{connectionId}/keys/delete`	`keys:delete`	Delete one or more keys
`POST`	`/api/v1/connections/{connectionId}/keys/expire`	`keys:write`	Set or clear a key’s TTL
`POST`	`/api/v1/connections/{connectionId}/keys/export`	`transfer:export`	Export keys as the store’s own serialisation
`POST`	`/api/v1/connections/{connectionId}/keys/import`	`transfer:import`	Restore exported keys
`GET`	`/api/v1/connections/{connectionId}/keys/migrate`	`migration:run`	Migrations started from this target
`POST`	`/api/v1/connections/{connectionId}/keys/migrate`	`migration:run`	Move keys to another target
`DELETE`	`/api/v1/connections/{connectionId}/keys/migrate/{jobId}`	`migration:run`	Stop a migration
`POST`	`/api/v1/connections/{connectionId}/keys/purge`	`keys:delete`	Delete everything a pattern matches
`POST`	`/api/v1/connections/{connectionId}/keys/rename`	`keys:write`	Rename a key
`GET`	`/api/v1/connections/{connectionId}/keys/tree`	`keys:read`	List the namespace level below a prefix
`DELETE`	`/api/v1/connections/{connectionId}/keyspace-watch`	`keys:read`	Give a lease back
`GET`	`/api/v1/connections/{connectionId}/keyspace-watch`	`keys:read`	Whether this target’s changes are being heard
`POST`	`/api/v1/connections/{connectionId}/keyspace-watch`	`keys:read`	Take or renew a lease on this target’s changes
`POST`	`/api/v1/connections/{connectionId}/keyspace-watch/announce`	`server:configure`	Ask the target to announce its changes

Migrations
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/migrations`	Oturum açmış olmak	Every migration this instance knows about

Monitoring
Yöntem	Yol	Gereken	Ne yapar
`DELETE`	`/api/v1/connections/{connectionId}/monitoring`	`monitoring:manage`	Stop sampling this target
`GET`	`/api/v1/connections/{connectionId}/monitoring`	`monitoring:read`	Sampling state and the readings collected so far
`POST`	`/api/v1/connections/{connectionId}/monitoring`	`monitoring:manage`	Start sampling this target
`GET`	`/api/v1/connections/{connectionId}/monitoring/big-keys`	`monitoring:read`	The largest keys in a sample of the keyspace
`GET`	`/api/v1/connections/{connectionId}/monitoring/clients`	`monitoring:read`	Clients currently attached to the server
`DELETE`	`/api/v1/connections/{connectionId}/monitoring/clients/{clientId}`	`monitoring:manage`	Disconnect a client
`GET`	`/api/v1/connections/{connectionId}/monitoring/history`	`monitoring:read`	Readings over a window
`GET`	`/api/v1/connections/{connectionId}/monitoring/info`	`monitoring:read`	Raw server statistics, grouped by section
`GET`	`/api/v1/connections/{connectionId}/monitoring/sample`	`monitoring:read`	One reading of this target’s vital signs, taken now
`DELETE`	`/api/v1/connections/{connectionId}/monitoring/slowlog`	`monitoring:manage`	Clear the slow log
`GET`	`/api/v1/connections/{connectionId}/monitoring/slowlog`	`monitoring:read`	Commands the server recorded as slow, newest first

Preferences
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/preferences`	Oturum açmış olmak	Everything you prefer
`POST`	`/api/v1/preferences`	Oturum açmış olmak	Set one preference
`DELETE`	`/api/v1/preferences/{name}`	Oturum açmış olmak	Forget one preference

Pub/Sub
Yöntem	Yol	Gereken	Ne yapar
`POST`	`/api/v1/connections/{connectionId}/pubsub/publish`	`pubsub:publish`	Publish a message
`DELETE`	`/api/v1/connections/{connectionId}/pubsub/subscription`	`pubsub:subscribe`	Stop listening on this target
`GET`	`/api/v1/connections/{connectionId}/pubsub/subscription`	`pubsub:subscribe`	What this target is currently subscribed to
`POST`	`/api/v1/connections/{connectionId}/pubsub/subscription`	`pubsub:subscribe`	Listen on a target’s channels
`GET`	`/api/v1/subscriptions`	`viewer`, `operator`, `admin`	Every subscription this server currently holds open

Roles
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/authz/roles`	`admin`	Every role and what it carries
`POST`	`/api/v1/authz/roles`	`admin`	Create a custom role
`DELETE`	`/api/v1/authz/roles/{id}`	`admin`	Remove a custom role
`PUT`	`/api/v1/authz/roles/{id}`	`admin`	Change a custom role
`GET`	`/api/v1/authz/roles/permissions`	`admin`	Every permission there is

Schedules
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/schedules`	`operator`, `admin`	Every schedule, with when it last ran and when it runs next
`POST`	`/api/v1/schedules`	`schedule:manage`	Arrange work to happen on its own
`DELETE`	`/api/v1/schedules/{id}`	`schedule:manage`	Remove a schedule, and the record of what it did
`PUT`	`/api/v1/schedules/{id}`	`schedule:manage`	Change a schedule
`POST`	`/api/v1/schedules/{id}/run`	`schedule:manage`	Run it now
`GET`	`/api/v1/schedules/job-types`	`operator`, `admin`	The kinds of work that can be scheduled
`GET`	`/api/v1/schedules/runs`	`operator`, `admin`	What the schedules have done

Second factor
Yöntem	Yol	Gereken	Ne yapar
`DELETE`	`/api/v1/auth/second-factor`	Oturum açmış olmak	Turn off your second factor
`GET`	`/api/v1/auth/second-factor`	Oturum açmış olmak	Whether you have a second factor, and how many recovery codes are left
`POST`	`/api/v1/auth/second-factor`	Oturum açmış olmak	Begin pairing an authenticator
`POST`	`/api/v1/auth/second-factor/confirm`	Oturum açmış olmak	Prove the pairing with one code
`POST`	`/api/v1/auth/second-factor/recovery-codes`	Oturum açmış olmak	Replace your recovery codes

Security
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/acl`	`acl:read`	Users the target knows about
`PUT`	`/api/v1/connections/{connectionId}/acl`	`acl:manage`	Create or replace a user
`DELETE`	`/api/v1/connections/{connectionId}/acl/{username}`	`acl:manage`	Remove a user from the target
`GET`	`/api/v1/connections/{connectionId}/acl/categories`	`acl:read`	Permission categories the target defines
`GET`	`/api/v1/security/audit`	`audit:read`	What has been done, newest first
`GET`	`/api/v1/security/audit/actions`	`audit:read`	The action names recorded so far
`GET`	`/api/v1/security/me`	Herkese açık	Who Keydra thinks is asking, and what they may do

Server groups
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/authz/server-groups`	`admin`	Every server group, with the targets in it
`POST`	`/api/v1/authz/server-groups`	`admin`	Create a server group
`DELETE`	`/api/v1/authz/server-groups/{id}`	`admin`	Remove a server group
`DELETE`	`/api/v1/authz/server-groups/{id}/servers/{connectionId}`	`admin`	Take a target out of this group
`POST`	`/api/v1/authz/server-groups/{id}/servers/{connectionId}`	`admin`	Put a target into this group

ServerAdministration
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/admin/persistence`	`server:read`	How this target is keeping its data
`POST`	`/api/v1/connections/{connectionId}/admin/persistence/rewrite`	`server:configure`	Rewrite the append-only log, compacting it
`POST`	`/api/v1/connections/{connectionId}/admin/persistence/snapshot`	`server:configure`	Write a snapshot in the background
`GET`	`/api/v1/connections/{connectionId}/admin/settings`	`server:read`	Everything this target is configured to do
`POST`	`/api/v1/connections/{connectionId}/admin/settings`	`server:configure`	Change one setting while the server runs
`POST`	`/api/v1/connections/{connectionId}/admin/settings/persist`	`server:configure`	Write the running configuration back to the server’s own file

Sessions
Yöntem	Yol	Gereken	Ne yapar
`DELETE`	`/api/v1/auth/sessions`	Oturum açmış olmak	End every session except this one
`GET`	`/api/v1/auth/sessions`	Oturum açmış olmak	The browsers you are signed in on
`DELETE`	`/api/v1/auth/sessions/{id}`	Oturum açmış olmak	End one of your sessions

Sign-in policy
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/auth/policy`	`policy:manage`	What is asked of whoever signs in
`PUT`	`/api/v1/auth/policy`	`policy:manage`	Require a second factor, or stop requiring one

Sign-in providers
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/auth/providers`	Oturum açmış olmak	The ways in this instance offers
`GET`	`/api/v1/auth/providers/{key}/callback`	Oturum açmış olmak	Where the provider sends people back to
`GET`	`/api/v1/auth/providers/{key}/start`	Oturum açmış olmak	Begin signing in through a provider

Topology
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/topology`	`connection:view`	How this target is arranged and what it supports

Tunnels
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/tunnels`	`admin`	Every configured tunnel
`POST`	`/api/v1/tunnels`	`admin`	Add a tunnel
`DELETE`	`/api/v1/tunnels/{id}`	`admin`	Remove a tunnel
`PUT`	`/api/v1/tunnels/{id}`	`admin`	Change a tunnel
`POST`	`/api/v1/tunnels/{id}/check`	`admin`	Find out whether it works
`POST`	`/api/v1/tunnels/check`	`admin`	Try a jump host that has not been saved

Users
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/authz/users`	`admin`	Everybody, with the groups they are directly in
`POST`	`/api/v1/authz/users`	`admin`	Create a local account
`DELETE`	`/api/v1/authz/users/{id}`	`admin`	Remove an account
`PUT`	`/api/v1/authz/users/{id}`	`admin`	Change an account

Values
Yöntem	Yol	Gereken	Ne yapar
`GET`	`/api/v1/connections/{connectionId}/value`	`values:read`	Read a page of a key’s value
`POST`	`/api/v1/connections/{connectionId}/value`	`values:write`	Change a value
`GET`	`/api/v1/connections/{connectionId}/value/encodings`	`viewer`, `operator`, `admin`	List the decoders a client may request

GraphQL işlemleri#

Keydra arayüzünün gerçekte kullandığı işlemler. Mutasyonlar da listededir: yüzey salt okunur değildir.

query
İşlem	Gereken	Ne yapar
`accounts`	`users:manage`	Every account, with the roles it holds
`aclCategories`	`acl:read`	The command categories a rule can name, as this server spells them
`aclUsers`	`acl:read`	The accounts the server itself knows about, and what each may run
`alertDeliveries`	`alert-delivery:manage`	The channels a firing rule can send word through
`alertEvents`	`viewer`, `operator`, `admin`	What has fired and what has cleared, newest first
`alertMetrics`	`viewer`, `operator`, `admin`	The metrics a rule can watch, each with its unit
`alertRules`	`viewer`, `operator`, `admin`	The rules, with what each one is reading now and which state it is in
`askableCommands`	`admin`	Commands a target can be allowed to run, each with what allowing it means
`auditActions`	`audit:read`	Every kind of action that has been recorded, for a filter to offer
`auditLog`	`audit:read`	A page of the audit log, newest first
`authState`	Oturum açmış olmak	What this instance expects of whoever is asking
`backup`	`transfer:import`	One backup’s header, read without downloading the whole file
`backupDestinations`	`backup:manage`	Every destination, without the credentials they hold
`backups`	`transfer:import`	What is already in a destination, newest first
`biggestKeys`	`monitoring:read`	The biggest keys found by sampling the keyspace
`capabilities`	`connection:view`	What a target can do, which decides which tools are offered for it
`clients`	`monitoring:read`	Who is connected to the target right now
`connection`	`connection:view`	One target, by id
`connections`	`viewer`, `operator`, `admin`	Every target the caller can see, with its last known status
`consoleHistory`	`console:run`	What you have run against this target, newest first, with values redacted
`databases`	`connection:view`	The numbered databases on a target, with how many keys each holds
`deniedCommands`	`console:run`	The commands this target refuses to run, whoever is asking
`effectivePermissions`	Oturum açmış olmak	What the caller may do, over Keydra itself and over each target
`encryptionStatus`	`crypto:rotate`	Which key the stored secrets are under, and how many are not
`flaggedSignInCount`	`audit:read`	How many flagged sign-ins there are in the window
`flaggedSignIns`	`audit:read`	Sign-ins that worked but did not look like the ones before them
`fleet`	`viewer`, `operator`, `admin`	One reading from every target the caller can see
`grants`	`grants:manage`	Who holds which role, over what
`groups`	`groups:manage`	Every group, with who is in it
`identityProviders`	`idp:manage`	Every provider, with the redirect URI each one has to be told about
`keyspaceReport`	`analysis:read`	What the keyspace holds, worked out by sampling it
`keyspaceWatch`	`keys:read`	Whether a target announces its changes, and whether anybody is listening
`me`	Oturum açmış olmak	Who is asking, the roles they hold, and whether access is being enforced
`migrations`	`viewer`, `operator`, `admin`	A page of migrations, newest first, filtered to what the caller can see
`monitoring`	`monitoring:read`	Whether a target is being sampled, and since when
`monitoringHistory`	`monitoring:read`	Readings between two moments, evenly divided into points
`monitoringSample`	`monitoring:read`	One reading, taken now
`mySessionCount`	Oturum açmış olmak	How many browsers there are to page through
`mySessions`	Oturum açmış olmak	Every browser that can act as you right now, the one reading this first
`mySignInCount`	Oturum açmış olmak	How many sign-ins there are to page through
`mySignIns`	Oturum açmış olmak	Your own recent sign-ins, newest first
`namespaceTree`	`keys:read`	One level of the keyspace, grouped by a delimiter
`permissionCatalogue`	`grants:manage`	Every permission a role can carry, with the level it applies at
`persistence`	`server:read`	Whether the server is writing to disk, and when it last did
`refusedSignIns`	`audit:read`	Sign-ins that were refused, newest first
`roles`	`grants:manage`	Every role, built in or defined here, with the permissions it carries
`scheduleJobTypes`	`operator`, `admin`	The kinds of work that can be scheduled, with the permission each one needs
`scheduleRuns`	`operator`, `admin`	What became of the arranged work, newest first
`schedules`	`operator`, `admin`	Every schedule, with when it last ran and when it runs next
`serverGroups`	`groups:manage`	Every server group, with which targets are in it
`serverSettings`	`server:read`	The server’s own configuration, as it reports it
`signInOptions`	Oturum açmış olmak	The ways of signing in this instance offers, other than a password here
`signInPolicy`	`policy:manage`	What this instance asks of whoever signs in
`slowLog`	`monitoring:read`	The commands the server itself recorded as slow
`subscription`	`pubsub:subscribe`	What this target is being listened to for, or nothing
`topology`	`connection:view`	The shape of the target: standalone, replicated, sentinel or clustered
`tunnels`	`tunnel:manage`	Every jump host, without the keys they hold

mutation
İşlem	Gereken	Ne yapar
`addGroupMember`	`groups:manage`	Puts an account, or another group, inside a group
`addProviderGroupMapping`	`idp:manage`	Says which local group a claim value puts somebody in
`addServerToGroup`	`groups:manage`	Puts a target in a server group
`announceKeyspaceChanges`	`server:configure`	Asks a target to announce its changes, keeping whatever its setting already said
`cancelMigration`	`migration:run`	Stops a migration; what has moved stays moved
`changeServerSetting`	`server:configure`	Changes one setting on the running server
`checkAlertDelivery`	`alert-delivery:manage`	Sends a test message through a channel and reports what happened
`checkBackupDestination`	`backup:manage`	Reaches the destination and reports what happened
`checkConnection`	`connection:create`	Opens a connection to the target and reports what came back
`checkTunnel`	`tunnel:manage`	Opens the tunnel and reports what happened
`clearConsoleHistory`	`console:run`	Empties your own command history on this target
`clearSlowLog`	`monitoring:manage`	Empties the server’s own slow log
`copyKey`	`keys:write`	Copies a key, here or to another target
`createAccount`	`users:manage`	Adds an account; the password is set by whoever accepts the invitation
`createAlertDelivery`	`alert-delivery:manage`	Adds a channel for firing rules to send word through
`createAlertRule`	`alert:manage`	Adds a rule watching one metric on one target
`createBackupDestination`	`backup:manage`	Adds a destination for backups to be written to
`createConnection`	`connection:create`	Adds a target
`createGroup`	`groups:manage`	Adds a group
`createIdentityProvider`	`idp:manage`	Adds a provider people can sign in through
`createRole`	`grants:manage`	Defines a role
`createSchedule`	`schedule:manage`	Arranges a job to run on a cron expression
`createServerGroup`	`groups:manage`	Adds a server group, so a grant can name several targets at once
`createTunnel`	`tunnel:manage`	Adds a jump host
`deleteAccount`	`users:manage`	Removes an account and every grant it held
`deleteAclUser`	`acl:manage`	Removes one of the server’s own accounts
`deleteAlertDelivery`	`alert-delivery:manage`	Removes a channel
`deleteAlertRule`	`alert:manage`	Removes a rule
`deleteBackupDestination`	`backup:manage`	Removes a destination
`deleteConnection`	`connection:delete`	Removes a target and everything Keydra kept about it
`deleteGroup`	`groups:manage`	Removes a group and every grant it held
`deleteIdentityProvider`	`idp:manage`	Removes a provider; accounts it created stay, and can no longer sign in with it
`deleteKeys`	`keys:delete`	Removes the named keys
`deleteRole`	`grants:manage`	Removes a role and every grant of it
`deleteSchedule`	`schedule:manage`	Removes a schedule
`deleteServerGroup`	`groups:manage`	Removes a server group and every grant scoped to it
`deleteTunnel`	`tunnel:manage`	Removes a jump host
`endOtherSessions`	Oturum açmış olmak	Ends every session but this one, and answers how many
`endSession`	Oturum açmış olmak	Ends one of your sessions; it stops on that browser’s next request
`expireKey`	`keys:write`	Sets or clears a key’s time to live
`generateBackupKeyPair`	`backup:manage`	Makes a key pair; the private half is shown once and never stored
`grant`	`grants:manage`	Gives a role to an account or a group, over an instance, group or target
`holdKeyspaceWatch`	`keys:read`	Takes or renews a lease on a target’s changes
`importKeys`	`transfer:import`	Writes keys into a target from what was exported
`inviteAccount`	`users:manage`	Makes a link that lets an account set its own password
`killClient`	`monitoring:manage`	Closes one client’s connection to the target
`persistServerSettings`	`server:configure`	Writes the running configuration to the server’s own file
`publish`	`pubsub:publish`	Sends a message to a channel and answers how many subscribers took it
`purgeKeys`	`keys:delete`	Removes every key matching a glob, a batch at a time
`reencryptSecrets`	`crypto:rotate`	Rewrites every stored secret under the current key
`releaseKeyspaceWatch`	`keys:read`	Gives a lease back, closing the watch when it was the last
`removeGroupMember`	`groups:manage`	Takes a member out of a group
`removeProviderGroupMapping`	`idp:manage`	Removes a mapping; it stops applying at the next sign-in through that provider
`removeServerFromGroup`	`groups:manage`	Takes a target out of a server group
`renameKey`	`keys:write`	Renames a key
`requireSecondFactor`	`policy:manage`	Require a second factor of every local account, or stop requiring one
`restoreBackup`	`transfer:import`	Writes a backup’s keys into a target
`revoke`	`grants:manage`	Takes a grant back; it stops applying on the holder’s next request
`rewriteAppendLog`	`server:configure`	Asks the server to rewrite its append-only file
`runSchedule`	`schedule:manage`	Runs a scheduled job now, without waiting for its cron
`setAclUser`	`acl:manage`	Creates or replaces one of the server’s own accounts
`startMigration`	`migration:run`	Starts moving keys from one target to another; answers before any have moved
`startMonitoring`	`monitoring:manage`	Starts sampling a target on a clock
`stopMonitoring`	`monitoring:manage`	Stops sampling a target
`subscribe`	`pubsub:subscribe`	Starts listening to channels or patterns on a target
`takeBackup`	`transfer:export`	Writes a backup of a target into a destination
`takeSnapshot`	`server:configure`	Asks the server to write a snapshot in the background
`unsubscribe`	`pubsub:subscribe`	Stops listening; answers whether anything was listening
`updateAccount`	`users:manage`	Changes an account
`updateAlertDelivery`	`alert-delivery:manage`	Changes a channel
`updateAlertRule`	`alert:manage`	Changes a rule
`updateBackupDestination`	`backup:manage`	Changes a destination
`updateConnection`	`connection:edit`	Changes a target
`updateIdentityProvider`	`idp:manage`	Changes a provider
`updateRole`	`grants:manage`	Changes what a role carries
`updateSchedule`	`schedule:manage`	Changes a schedule
`updateTunnel`	`tunnel:manage`	Changes a jump host

subscription
İşlem	Gereken	Ne yapar
`keys`	`keys:read`	Walks a target’s keyspace with SCAN, one key at a time. KEYS is never used.

Sınırlar

Şema, tek bir isteği ağır bir işe dönüştürmenin bilinen bütün yolları için sınır koyar: sorgunun kaç kat iç içe geçebileceği, toplamda kaç alan istenebileceği — takma ad saldırısını yalnızca derinlik sınırı yakalayamaz — ve ayrıştırıcının okumayı bırakmadan önce ne kadar kabul edeceği. Her biri ayrıca ayarlanmıştır; büyük belgelerle çalışan genel API’ler için düşünülmüş varsayılanlara bırakılmamıştır.

Beklenmeyen hatalar tek bir genel cümleyle yanıtlanır. Uygulamanın içinden gelen istisna mesajı, uygulamanın yapısını anlatır; onun yeri günlüktür.

Bu sayfayı düzenle