Kulcsok és biztonság

Egy appnak egyszerre több érvényes client_secret-je lehet (legfeljebb 5), így a kulcscsere leállás nélkül megy:

1. A portálon az app „Hitelesítés” fülén kérj „Új titkos kulcs”-ot, és válaszd ki, mikor járjanak le a régiek (alapból 24 óra múlva, legfeljebb 30 nap). Az új kulcs csak egyszer látszik.
2. Telepítsd az új kulcsot a szervereden. Az átfedés alatt a régi és az új is érvényes mindenhol, ahol a client_secret-et küldöd (token-csere, /api/apps/embed/verify).
3. A régi kulcs a megadott időben magától lejár. Ha minden példányod átállt, előbb is visszavonhatod - a listában látod, melyik kulcsot mikor használták utoljára.

• Kiszivárgás gyanújánál ne várj átfedésre: kérj új kulcsot úgy, hogy a régiek azonnal lejárjanak, vagy vond vissza a kiszivárgott kulcsot.
• Legalább egy lejárat nélküli kulcs mindig marad: az utolsót nem lehet visszavonni, előbb újat kell létrehoznod.
• A csere nem érinti a telepítések dxk_ kulcsait, az embed_secret-et és a webhook_secret-et: a futó telepítéseid a csere alatt is működnek.
• Az esemény-titok külön titok (az életciklus-események aláírásához), és egyszerre egy él belőle. A cseréje azonnali: amíg az újat nem telepíted, az ellenőrzésed elutasítja az eseményeket, és az újrapróbálás hozza őket újra.

Ha a fejlesztői fiókot többen használjátok, a kulcsokat csak az a szerep éri el, amelyik appot épít; erről a Csapat és szerepek oldal szól.

A v3 API minden válasza kap egy kérés-azonosítót, a hitelesített válaszok pedig a percenkénti keret állását is hordozzák.

A hiba-törzsben is ott az azonosító (error.request_id), a hiányzó hatókör miatti 403-nál pedig az is, melyik hatókör kellett volna (error.required_scope):

403 { "error": { "code": "forbidden", "message": "Token lacks required scope: contacts.write.",                 "required_scope": "contacts.write", "request_id": "req_…" } }

1try {2  await dynex.contacts.create({ email: "anna@example.com" });3} catch (e) {4  if (e instanceof DynexApiError) {5    console.error(e.status, e.code, e.message, "request_id:", e.requestId); // mindig naplózd6    if (e.requiredScope) console.error("hiányzó hatókör:", e.requiredScope);7    if (e.isRateLimited) await sleep((e.retryAfterSec ?? 1) * 1000);8  }9}10dynex.lastRateLimit; // { limit, remaining, resetSec } az utolsó válaszból11dynex.lastRequestId; // az utolsó válasz azonosítója, sikeres hívásnál is

• Mit látsz a „Napló” fülön: teszt-fiókos telepítésnél a kéréseket a kérés és a válasz törzsével együtt (a titkok kitakarva), 7 napig. Éles telepítésnél csak a hibás kéréseket, törzs és fiók-azonosító nélkül, 14 napig. A 429-es válaszok nem kerülnek a naplóba.
• Ezeket a fejléceket a /api/v3 végpontjai küldik; a leíró végpontok (/api/v3 gyökér, openapi.json, postman.json) és a régi /api/v1 nem.

• Minden URL (app_url, redirect_uri, webhook_url) https; fejlesztéshez kizárólag http://localhost engedett.
• A redirect_uri pontosan egyezik a regisztrált listával - nincs minta, nincs prefix, nincs query-eltérés.
• A client_secret, a dxk_ kulcs és az embed_secret csak a szervereden él; soha ne kerüljön böngészőbe, mobil-appba vagy repóba. A Dynex a secretet és a kulcsot hashelve tárolja. Kiszivárgás gyanújánál cseréld le a client_secret-et a fejlesztői portálon (lásd: Több titkos kulcs). Az embed_secret telepítésenként más, így egy kiszivárgott érték csak azt az egy telepítést érinti; a helyi ellenőrzés mellé a távoli /api/apps/embed/verify ellenőrzést is érdemes használni.
• Az appod bizalmas kliens: a token-csere a szervereden fut a client_secret-tel. A PKCE S256 kiegészítő védelem, nem helyettesíti.
• A state paramétert véletlenből képezd, a felhasználó sessionjében (HttpOnly süti) tárold, és a callbackben ezzel vesd össze; hiányzó session-értéknél utasítsd el a callbacket (az SDK readCallbackParams-a üres elvárt state-nél null-t ad). A függő state-eket 10 perc után takarítsd.
• A beágyazási tokent minden betöltéskor ellenőrizd (aláírás + lejárat), ne naplózd, és váltsd saját sessionre; a híd üzeneteit csak a Dynex originről és csak a szülő ablaktól fogadd el; a beágyazott oldal küldjön frame-ancestors CSP-t.
• A kontextus mezői (tenantName, userEmail, …) és a callback paraméterei idegen bevitel: HTML-be csak escape-elve.
• Fejlesztői/diagnosztikai végpontot, ami bérlői adatot ad vissza, ne hagyj nyitva (tunnel mögött sem).
• Webhookot csak érvényes aláírással dolgozz fel; a bérlőt az aláírt törzs tenantId-jából vedd, ne a URL-ből.
• Két webhook-csatorna, két titok: app.* eseményt csak az app esemény-titkával ellenőrizve (parseAppEvent) fogadj el, a telepítés webhook_secret-jével soha. Az X-Dynex-Channel fejléc nincs aláírva, önmagában semmit nem bizonyít.
• A kulcs a telepítés hatóköreire korlátozott; ami nem kell, ne kérd. Egy 403 forbidden válasz hiányzó hatókört jelent - hogy melyiket, azt az error.required_scope mező mondja meg.
• Tenant-izoláció nálad is: minden tárolt adatot az install_id / tenant_id alá köss, és eltávolításkor (app.uninstalled esemény; a kulcs ekkor már 401-et ad) töröld a bérlő adatait.
• Kvóta: a kulcsra a v3 API percenkénti és napi keretei érvényesek. A percenkénti keret állását az X-RateLimit-* fejlécek mutatják (tájékoztató érték), a túllépést a 429 státusz jelzi, a várakozás hosszát a Retry-After fejléc.