Relay API

Solidus Relay, relay.solidus.network için bir DIDComm v2 mesajlaşma aracısı / mediatörüdür. Solidus DID’leri arasında şifrelenmiş DIDComm mesajlarını yönlendiren, zincire sabitlenmiş bir aracıdır — ajanlar (cüzdanlar, kimlik bilgisi düzenleyicileri, doğrulayanlar) aracılık için kaydolur (CoordinateMediation 2.0) ve aracı, şifrelenmiş mesajlarını (Pickup Protocol 3.0) tutar ve teslim eder, böylece aynı anda çevrimiçi olmaları gerekmez. Aracı, okuyamadığı JWE şifreli zarfları yönlendirir.

Relay bir mesaj hattıdır, bir KYC, cüzdan, ödeme veya ajan ürünü değildir — bunlar, DIDComm mesajlarını taşıdığı kardeş yüzeylerdir.

Temel URL: https://relay.solidus.network

DIDComm teli (POST /didcomm, GET /invite) önek almaz. Operatör yönetim REST’i /v1/* altında yer alır.

Kimlik Doğrulama

İki mekanizma, iki farklı çağıran için:

• Operatör oturumu — operatör konsolu, doğrulanmış bir auth.solidus.network OIDC id_token’ını POST /v1/auth/session üzerinden bir aracı oturum JWT’siyle değiştirir, ardından bunu Authorization: Bearer <session-jwt> olarak gönderir. Tam erişim.
• API anahtarı — iptal edilebilir bir anahtar, Authorization: Bearer slk_..., read, manage veya full’a kapsamlanmış. Operatör konsolu aracılığıyla oluşturulur (kendi kendine hizmet veren herkese açık bir kayıt rotası yoktur — operatör hesapları, bir POST /v1/operators çağrısı yerine OIDC devri aracılığıyla sağlanır).

requireAuth olarak işaretlenmiş rotalar her ikisini de kabul eder. requireManage olarak işaretlenmiş rotalar ayrıca yazma kapsamına ihtiyaç duyar (bir operatör oturumu her zaman tam erişimlidir; read kapsamlı bir API anahtarı 403 ile reddedilir).

curl https://relay.solidus.network/v1/mediations \
  -H "Authorization: Bearer slk_..."

POST /didcomm ve GET /invite, bearer kimlik doğrulaması gerektirmez — DIDComm zarfının kendisi kimin konuştuğunun kanıtını taşır (aracının anahtarına şifrelenmiştir) ve OOB daveti tasarım gereği herkese açık bir önyükleme belgesidir.

Rota dizini

DIDComm teli

OOB daveti

Aracılık kurmak isteyen dış ajanlar için kimlik doğrulaması yapılmamış önyükleme belgesi.

curl https://relay.solidus.network/invite

// Response 200 — measured live
{
  "type": "https://didcomm.org/out-of-band/2.0/invitation",
  "id": "relay-invite-23c69ca7",
  "from": "did:key:z6LSsMkRXWM9YLF3f15cEvBtjWneDrbLjto2S53mDJqy8aT8",
  "body": {
    "goal_code": "request-mediate",
    "goal": "Coordinate mediation with the Solidus relay",
    "accept": ["didcomm/v2"]
  },
  "services": [
    {
      "id": "#relay",
      "type": "DIDCommMessaging",
      "serviceEndpoint": {
        "uri": "https://relay.solidus.network/didcomm",
        "accept": ["didcomm/v2"],
        "routingKeys": ["did:key:z6LSsMkRXWM9YLF3f15cEvBtjWneDrbLjto2S53mDJqy8aT8"]
      }
    }
  ]
}

POST /didcomm

Tek makine uç noktası. Ham bir DIDComm şifreli zarfı kabul eder (Content-Type: application/didcomm-encrypted+json, gövde ayrıştırılmamış — aracı motoru tam baytları açar). İç mesaj type’ına göre dağıtır:

• https://didcomm.org/routing/2.0/forward — mesajı çevrimdışı bir alıcı için kuyruğa alır. DIDComm yanıtı yok; HTTP yanıtı yalnızca bir durum kodudur.
• https://didcomm.org/coordinate-mediation/2.0/* — aracılık isteği/onayı/reddi/anahtar listesi güncellemesi. Tanımlanabilir bir gönderen gerektirir.
• https://didcomm.org/messagepickup/3.0/* — kuyruğa alınmış mesajları alır. Tanımlanabilir bir alıcı gerektirir.

Başka herhangi bir mesaj type’ı 400 döndürür. Bir GET /didcomm 404 döndürür — bu doğrudur; tel yalnızca POST’tur.

curl -X POST https://relay.solidus.network/didcomm \
  -H "Content-Type: application/didcomm-encrypted+json" \
  --data-binary @envelope.json

Yanıt, varsa, kendisi paketlenmiş bir DIDComm zarfıdır (application/didcomm-encrypted+json) — aracı gönderenlerini çözümleyebildiğinde gönderene authcrypt geri döner, aksi halde anoncrypt.

DID başına hız sınırlama

Tanımlanabilir bir gönderen DID’ine sahip her zarf, gönderilmeden önce kiracı başına bir rate_limit_per_did_per_min’e karşı kontrol edilir. Sınırın üzerinde 429 döndürür.

Operatör oturumu

curl -X POST https://relay.solidus.network/v1/auth/session \
  -H "content-type: application/json" \
  -d '{"id_token": "<verified auth.solidus.network id_token>"}'

// Response 200
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": "12h",
  "operator": { "id": "...", "did": "did:solidus:testnet:...", "email": "[email protected]", "role": "admin" }
}

curl https://relay.solidus.network/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response 200
{
  "authenticated": true,
  "tenantId": "...",
  "operator": { "id": "...", "did": "did:solidus:testnet:...", "email": "[email protected]", "role": "admin", "plan": "..." },
  "via": "session"
}

POST /v1/auth/logout durumsuzdur — konsol yalnızca token’ı atar; v0’da kısa ömürlü bir JWT için sunucu tarafında iptal edilecek hiçbir şey yoktur.

Aracılıklar

curl https://relay.solidus.network/v1/mediations \
  -H "Authorization: Bearer slk_..."

// Response 200 — shape
[
  {
    "id": "...",
    "recipientDid": "did:solidus:testnet:...",
    "state": "granted",
    "gate": { "policy": "kyc-gate", "state": "pass" },
    "keylistSize": 2,
    "queued": 0,
    "delivered24h": 5,
    "grantedAgo": "3h ago",
    "protocols": ["forward", "pickup"]
  }
]

state, requested, granted, denied, revoked’tan biridir. Onaylama/reddetme/iptal etme hepsi requireManage’dir:

curl -X POST https://relay.solidus.network/v1/mediations/<id>/grant -H "Authorization: Bearer slk_..."
curl -X POST https://relay.solidus.network/v1/mediations/<id>/deny  -H "Authorization: Bearer slk_..." \
  -H "content-type: application/json" -d '{"reason": "credential check failed"}'
curl -X POST https://relay.solidus.network/v1/mediations/<id>/revoke -H "Authorization: Bearer slk_..."

GET /v1/mediations/:id/keylist, bir aracılık için kayıtlı yönlendirme anahtarlarını listeler; DELETE /v1/mediations/:id/keylist/:key bir tanesini kaldırır (requireManage).

Ajanlar

Salt okunur bileşik görünüm — yazma uç noktası yoktur.

curl https://relay.solidus.network/v1/agents -H "Authorization: Bearer slk_..."

// Response 200 — shape
[
  {
    "did": "did:solidus:testnet:...",
    "presence": "offline",
    "mediationState": "granted",
    "queued": 0,
    "ratePerMin": 0,
    "rateLimit": 60,
    "lastSeenAgo": "3h ago"
  }
]

presence, bugün her zaman "offline"dır — v0’ın bir WebSocket varlık kanalı yoktur, bu yüzden bu bir hata değil, dürüst bir statik değerdir.

Mesajlar ve kuyruk durumu

curl "https://relay.solidus.network/v1/messages?state=queued&limit=50" -H "Authorization: Bearer slk_..."

Sorgu parametreleri: state (queued, live-delivered, delivered, acknowledged, expired, failed), protocol (forward, pickup, coordinate-mediation), recipient, limit, offset.

curl https://relay.solidus.network/v1/queue/status -H "Authorization: Bearer slk_..."

Çözümlemeler — zincire sabitlenmiş yönlendirme görünürlüğü

Bir DID’in aracı/hizmet uç noktalarını zincir üzerindeki DID belgesinden çözümler — bu, ürünün kilit özelliğinin üzerine inşa edildiği “zincire sabitlenmiş yönlendirme”dir, zincir dışı bir kayıt defteri araması değil.

curl https://relay.solidus.network/v1/resolutions/did:solidus:testnet:... -H "Authorization: Bearer slk_..."

GET /v1/resolutions, kiracı için şu anda onaylanmış her aracılığın alıcı DID’ini çözümler. POST /v1/resolutions/:did/re-resolve, çözümleyicinin kendi önbelleğini atlayarak taze bir zincir üstü okumayı zorlar (requireManage).

Politikalar — kimlik bilgisi kapılı teslimat

curl -X POST https://relay.solidus.network/v1/policies \
  -H "Authorization: Bearer slk_..." -H "content-type: application/json" \
  -d '{"name":"KYC gate","credentialType":"KycLevel1Credential","disclosure":"selective (BBS+)","appliesTo":"mediation"}'

disclosure, full veya selective (BBS+)’tir; appliesTo, mediation, delivery veya both’tur.

curl -X POST https://relay.solidus.network/v1/policies/test \
  -H "Authorization: Bearer slk_..." -H "content-type: application/json" \
  -d '{"policyId":"...","credentialRef":"urn:solidus:credential:..."}'

POST /v1/policies/test, canlı aracılık/teslimat yolunun kullandığı aynı kapı kontrolünü çalıştırır — üretim davranışından sapacak ayrı bir simüle edilmiş uygulama yoktur.

GET/PUT /v1/policies/rate-limit ve GET/PUT /v1/policies/retention, DID başına hız sınırını ve mesaj saklama penceresini yönetir.

API anahtarları

curl -X POST https://relay.solidus.network/v1/api-keys \
  -H "Authorization: Bearer slk_..." -H "content-type: application/json" \
  -d '{"name":"CI integration key","scope":"read"}'

scope, read, manage veya full’dur. DELETE /v1/api-keys/:id bir anahtarı iptal eder.

Webhook’lar

curl -X PUT https://relay.solidus.network/v1/webhooks \
  -H "Authorization: Bearer slk_..." -H "content-type: application/json" \
  -d '{"url":"https://example.com/hooks/relay","events":["mediation.granted","delivery.failed"]}'

Mevcut olaylar: mediation.granted, mediation.denied, message.queued, message.delivered, delivery.failed, gate.blocked, resolution.failed.

POST /v1/webhooks/test, bir olay için bir test teslimatı gönderir.

Ayarlar

Teslimat günlüğü

curl "https://relay.solidus.network/v1/delivery-log?recipient=did:solidus:testnet:...&limit=50" \
  -H "Authorization: Bearer slk_..."

// Response 200 — shape
[{ "id": "...", "at": "2026-07-29T11:00:00.000Z", "level": "info", "message": "message delivered" }]

Sağlık

curl https://relay.solidus.network/v1/health

// Response 200 — measured live
{
  "status": "ok",
  "service": "relay.solidus.network",
  "version": "0.1.0",
  "network": "testnet",
  "time": "2026-07-29T11:23:56.521Z",
  "checks": {
    "postgres": { "ok": true, "ms": 5 },
    "redis": { "ok": true, "ms": 3 },
    "solidusRpc": { "ok": true, "ms": 7 }
  }
}

Hata biçimi

RFC 7807 Problem Details, her Solidus arka ucunda kullanılan aynı şekil:

{
  "type": "https://solidus.network/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "name is required",
  "instance": "/v1/policies"
}

Kelime Dağarcığı

Relay bir DIDComm aracısıdır: aracılık, mesaj alma/teslimat, anahtar listesi, iletme/yönlendirme, şifreli (JWE) zarflar, DID’den DID’e mesajlaşma, zincire sabitlenmiş yönlendirme, kimlik bilgisi kapılı teslimat. Bu bir gaz sponsorluğu, paymaster veya meta-işlem aracısı değildir — bu, daha önce bu alt alan adını işgal eden farklı, arşivlenmiş bir üründü — ve kendisi bir KYC, cüzdan, ödeme veya ajan ürünü değildir.