API-kulcs létrehozása és kezelése

Published: 2026. július 16. · Last updated: 2026. július 21. · By Marcus Biel

Az API-kulcs oldal hitelesített hozzáférést biztosít egy külső rendszer számára a fiókjában támogatott Maildroppa API-végpontokhoz.

Létrehozhat egy API-kulcsot, kimásolhatja annak teljes titkos értékét, biztonságosan alaphelyzetbe állíthatja új kulcs létrehozásával, illetve törölheti, amikor már nincs rá szükség. Ugyanaz a fiókszintű kulcs használható szerveroldali integrációkhoz és a Maildroppa Automatizációk API-kérésindítóihoz is.

Az API-kulcs a Maildroppa-fiókját képviseli. Kezelje jelszóként: aki megszerzi a kulcsot, meghívhatja a hozzá elérhető API-végpontokat, amíg Ön új kulcsot nem hoz létre, vagy nem törli azt.

Mire szolgál az API-kulcs

Akkor használja az API-kulcsot, amikor egy Maildroppán kívüli szoftvernek interaktív felhasználói bejelentkezés nélkül kell együttműködnie a Maildroppával.

Gyakori példák:

• Feliratkozók szinkronizálása CRM-rendszerrel, áruházzal, tagsági rendszerrel vagy belső adatbázissal.
• Feliratkozók létrehozása vagy frissítése szerveroldali alkalmazásból.
• Címkék, mezők, mezőértékek és szegmensek olvasása vagy kezelése a támogatott végpontokon keresztül.
• Egyéni események küldése egy Automatizáció API-kérésindítójához.
• Tranzakciós e-mail-üzenetek küldése az API-n keresztül.
• API-alapú webhook-feliratkozások kezelése.

Az API-kulcs szerverek közötti kommunikációra szolgál. Nem használható látogató böngészőjében futó kódban, nyilvános webhelyen, mobilalkalmazásban vagy beágyazott feliratkozási űrlapban.

Az oldal jelenleg „béta” jelölést kapott. A jelenleg támogatott végpontok, kérés törzse, paraméterei és válaszsémái tekintetében a hivatkozott OpenAPI-dokumentáció az irányadó.

Az API-kulcs oldal megnyitása

Nyissa meg a „Beállítások” menüt, bontsa ki a „Fejlesztők” részt, majd válassza az „API-kulcs” lehetőséget.

Az oldalt közvetlenül itt is megnyithatja:

https://app.maildroppa.com/settings/developers/api-key

Az oldal a következőket tartalmazza:

• Egy API-kulcspanel béta-jelvénnyel.
• Egy „OpenAPI-dokumentáció megtekintése” hivatkozást.
• Üres állapotot és „API-kulcs létrehozása” gombot, ha nincs kulcs.
• Az aktuális kulcs maszkolt megjelenítését, ha létezik kulcs.
• Egy „Másolás” gombot, amely a teljes kulcsot másolja.
• „API-kulcs újragenerálása” és „API-kulcs törlése” műveleteket az aktuális kulcs lecseréléséhez vagy eltávolításához.

A Maildroppa fiókonként egy API-kulcsot engedélyez. Az oldal nem hoz létre külön kulcsokat az egyes alkalmazásokhoz, környezetekhez vagy csapattagokhoz.

API-kulcs létrehozása

Amikor az oldalon a „Még nincs API-kulcs” üzenet jelenik meg, kattintson az „API-kulcs létrehozása” gombra.

A Maildroppa azonnal létrehozza a kulcsot. Az első létrehozáshoz nem jelenik meg megerősítő párbeszédablak. A kérés feldolgozása közben a gomb felirata „API-kulcs létrehozása folyamatban” értékre változik, és az oldal ideiglenesen letiltja a további kulcsműveleteket.

A kulcs létrehozása után:

• Az üres állapot eltűnik.
• Megjelenik egy maszkolt kulcs.
• Elérhetővé válik a „Másolás”, az „API-kulcs újragenerálása” és az „API-kulcs törlése” művelet.
• A Maildroppa „API-kulcs frissítve” sikerüzenetet jelenít meg.

Ha a fiókhoz már tartozik egy kulcs, a Maildroppa nem hoz létre másodikat. Használja a meglévő kulcsot, vagy generáljon újat.

A maszkolt kulcs értelmezése

Az oldal nem jeleníti meg a teljes titkos értéket normál szövegként. Az első öt karaktert, majd öt csillagot mutat, például:

a1b2c*****

Ez csak vizuális maszkolás. A csillagok nem a kulcs valódi hosszát jelzik, és a maszkolt érték nem használható API-kéréshez.

A „Másolás” gombra kattintva a teljes aktuális kulcs a vágólapra kerül. Sikeres másolás után a gomb rövid időre „Másolva!” feliratúvá változik.

A kulcs az oldal újbóli megnyitásakor is maszkolva marad, de a „Másolás” továbbra is a teljes aktuális értéket másolja. Ezért nem szükséges érvényes kulcsot újragenerálnia pusztán azért, mert a létrehozásakor nem mentette el.

A kulcs biztonságos tárolása

A kimásolt kulcsot közvetlenül abba a titkos tárhelybe helyezze, amelyet az integráció használ.

Megfelelő helyek például:

• Kezelt titkoskulcs-kezelő.
• Védett szerveroldali környezeti konfiguráció.
• Titkosított telepítési titkos érték.
• Üzemeltetési helyreállításhoz használt jelszókezelő.

Ne tárolja a kulcsot a következő helyeken:

• Böngészőoldali JavaScriptben vagy más letölthető frontendcsomagban.
• Nyilvános vagy privát, verziótárba beküldött forráskódfájlban.
• URL-ben vagy lekérdezési paraméterként.
• Nyilvános dokumentációban, képernyőképen, támogatási üzenetben vagy hibakövetőben.
• Megosztott alkalmazásnaplókban, analitikai eseményekben vagy hibajelentésekben.
• Titkosítatlan táblázatban vagy normál csapatcsevegésben.

Ne adja hozzá a kulcsot olyan curl-példához, amelyet dokumentációba vagy másokkal megosztott shell-előzményekbe másolhatnak. Részesítse előnyben például a MAILDROPPA_API_KEY környezeti változót.

Az API-kulcs használata

A teljes kulcsot az X-API-Key HTTP-kérésfejlécben küldje:

X-API-Key: your-complete-api-key

Ne Bearer-tokenként küldje. A Maildroppa az X-API-Key fejlécet várja, nem az Authorization: Bearer ... formátumot.

Az éles API és interaktív OpenAPI-dokumentációja itt érhető el:

https://api.maildroppa.com

Kattintson az API-kulcs oldalon az „OpenAPI-dokumentáció megtekintése” hivatkozásra a dokumentáció új böngészőlapon való megnyitásához. Ott válasszon egy végpontot a metódus, az útvonal, a paraméterek, a kérés törzse, a válasz típusa és a lehetséges állapotkódok áttekintéséhez.

Példa kérés

Az alábbi példa a feliratkozók első oldalát kéri le. A kulcsot környezeti változóból olvassa be, ahelyett hogy közvetlenül a parancsba írná a titkos értéket:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

A változót abban a biztonságos környezetben állítsa be, amelyben az integráció fut. A pontos metódus, útvonal, lekérdezési paraméterek és törzs a végponttól függnek. Ezeket az OpenAPI-dokumentációból másolja ki, ne a Maildroppa alkalmazásban elérhető műveletek alapján próbálja kitalálni.

JSON-törzset tartalmazó kérések

JSON-t küldő kérés esetén ezt is adja meg:

Content-Type: application/json

Az alapvető szerkezet például:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

Az /example-endpoint és a törzse helyőrzők. Cserélje le őket egy dokumentált végpontra és annak dokumentált kérési sémájára.

Mihez biztosít hozzáférést a kulcs?

A kulcs csak az API-kulcsos hitelesítést támogató végpontokkal működik. Egy, a Maildroppa alkalmazás által belsőleg használt oldal vagy kérés nem válik automatikusan a nyilvános ügyfél-API részévé.

Az OpenAPI-dokumentáció mutatja be a támogatott ügyfél-API-t. Ha egy útvonal nincs API-kulcsos használatra dokumentálva, ne feltételezze, hogy a kulccsal hozzáférhető.

Az API-kulcs oldala nem kínál hatóköröket vagy végpontonkénti engedélyezési jelölőnégyzeteket. Ezért az aktuális fiókkulcsot kiemelten értékes hitelesítő adatként kell kezelni akkor is, ha egy integráció csak egyetlen végpontot használ.

Sebességkorlátok

A jelenlegi OpenAPI-szerződés a következő API-kulcsos korlátokat dokumentálja:

• Alapértelmezett ügyfél-API: percenként 300, óránként 2000 kérés.
• Események API a /events útvonalon: másodpercenként 100 kérés, 500 kéréses burstkapacitással.

Ezek a korlátok a Maildroppa-fiókra vonatkoznak, nem külön-külön minden, ugyanazt a kulcsot megosztó parancsfájlra. Ezért több integráció is ugyanazt a keretet fogyaszthatja.

Amikor a Maildroppa 429 Too Many Requests választ ad, állítsa le az új kérések küldését, és ha jelen van, tartsa be a válasz Retry-After fejlécét. Használjon várólistát és szabályozott visszalépést a sok párhuzamos újrapróbálkozás helyett.

A sebességkorlátozási szabályok változhatnak, amíg az API bétaállapotban van. Nagy forgalmú integrációk tervezése előtt ellenőrizze az OpenAPI-dokumentáció tetején található információkat.

A kulcs használata Automatizációs API-kérésekhez

Egy Automatizáció akkor indulhat el, amikor rendszere egyéni eseményt küld a Maildroppa Events API-jának.

Amikor „API-kérés” indítót állít be, a Maildroppa ugyanazt a fiók-API-kulcsot használja, amelyet ezen az oldalon kezel. Az indító beállítása létrehozhatja a kulcsot, ha még nem létezik, és kimásolhat egy előkészített curl-kérést, amely a teljes kulcsot tartalmazza.

Ennek két fontos következménye van:

• A fiókkulcs újragenerálása vagy törlése az Automatizációkhoz egyéni eseményeket küldő rendszereket is érinti.
• A kimásolt Automatizációs kérési példa tartalmazza a titkos értéket a vágólapon, még akkor is, ha a kulcs a képernyőn maszkolva jelenik meg.

A kulcs újragenerálása vagy törlése előtt vegyen fel minden API-kérésindítót és minden külső eseményküldőt az integrációs leltárába.

Az API-kulcs alaphelyzetbe állítása vagy cseréje

A „API-kulcs újragenerálása” lehetőséget akkor használja, ha vissza kell állítania vagy le kell cserélnie az aktuális hitelesítő adatot. A Maildroppa ugyanazon művelet részeként új kulcsot hoz létre, és érvényteleníti a korábbit.

Újragenerálást használjon, ha:

• A kulcs esetleg illetéktelenekhez került.
• Egy, a kulcsot ismerő személynek vagy szolgáltatónak már nincs szüksége hozzáférésre.
• Biztonsági szabályzata rendszeres hitelesítőadat-cserét ír elő.
• Egy régi vagy nem biztonságos helyen tárolt kulcsot szeretne lecserélni.

Kattintson a maszkolt kulcs alatti „API-kulcs újragenerálása” gombra. A Maildroppa figyelmeztető párbeszédablakot nyit, amelyben jelzi, hogy a meglévő kulcs többé nem lesz használható.

A folytatáshoz kattintson a párbeszédablakban az „API-kulcs újragenerálása” gombra, vagy az aktuális kulcs megtartásához a „Mégse” gombra.

Az újragenerálásnál nincs türelmi idő

Az újragenerálás megerősítése után a régi kulcs azonnal leáll. A Maildroppa nem tartja érvényben egyidejűleg a régi és az új kulcsot.

Mivel a fiókhoz csak egy kulcs tartozik, az újragenerálás minden azt használó szervert, ütemezett feladatot, integrációt, parancsfájlt és Automatizációs eseményküldőt érint.

Tervezett kulcscsere esetén ezt a sorrendet kövesse:

1. Listázza az összes, aktuális kulcsot használó integrációt.
2. Készítse elő az egyes integrációk titkos konfigurációjához és telepítési folyamatához való hozzáférést.
3. Ha a megszakítás nélküli API-hozzáférés fontos, válasszon rövid karbantartási időablakot.
4. Kattintson az „API-kulcs újragenerálása” gombra, majd erősítse meg a figyelmeztetést a párbeszédablakban az „API-kulcs újragenerálása” gombra kattintva.
5. Kattintson a „Másolás” gombra az új kulcs teljes értékének kimásolásához.
6. Azonnal cserélje le a titkos értéket minden integrációban.
7. Indítsa újra vagy telepítse újra azokat a szolgáltatásokat, amelyek csak induláskor töltik be a titkos értékeket.
8. Küldjön egy ártalmatlan, dokumentált kérést minden integráció ellenőrzéséhez.
9. Ellenőrizze, hogy érkeznek-e 401 Unauthorized válaszok egy elfelejtett, még a régi kulcsot használó szolgáltatástól.

Ha felmerül a gyanú, hogy az aktuális kulcs illetéktelenekhez került, azonnal generáljon újat, és fogadja el a jogos rendszerek frissítéséhez szükséges rövid kiesést.

Az API-kulcs törlése

Akkor törölje a kulcsot, ha a fiók többé nem fogadhat API-kulccsal hitelesített kéréseket.

Kattintson a maszkolt kulcs alatti „API-kulcs törlése” gombra. A Maildroppa figyelmeztető párbeszédablakot nyit, amelyben jelzi, hogy a kulcs véglegesen törlődik a fiókból.

A törléshez kattintson a párbeszédablakban az „API-kulcs törlése” gombra, vagy a megtartásához a „Mégse” gombra.

A törlés után:

• Az aktuális kulcs azonnal leáll.
• Az oldal visszatér a „Még nincs API-kulcs” állapothoz.
• A törölt kulcsot használó szerverintegrációk többé nem tudnak hitelesíteni.
• Az azt a kulcsot használó Automatizációs API-kérésküldők többé nem tudnak eseményeket kézbesíteni.

A kulcs törlése nem törli a feliratkozókat, kampányokat, címkéket, mezőket, szegmenseket, Automatizációkat vagy más fiókadatokat. Csak a támogatott API-végpontok eléréséhez használt hitelesítő adatot távolítja el.

Később az „API-kulcs létrehozása” gombra kattintva új hitelesítő adatot hozhat létre. A törölt érték nem állítható vissza. Minden integrációt frissíteni kell, mielőtt az új kulccsal használható lenne.

Újragenerálás vagy törlés: melyiket válassza?

Az „API-kulcs újragenerálása” lehetőséget válassza, ha az API-hozzáférésnek új hitelesítő adattal továbbra is működnie kell.

A törlést akkor válassza, ha az API-hozzáférést teljesen le szeretné állítani, legalább egy időre.

Mindkét művelet azonnal érvényteleníti az aktuális kulcsot. Az újragenerálás ugyanazon művelet részeként létrehozza a cserét; a törlés kulcs nélkül hagyja a fiókot.

Biztonsági javaslatok

Az API-kéréseket a szerveren tartsa

Egy böngésző vagy mobilalkalmazás nem képes megbízhatóan titokban tartani a beágyazott titkos értéket. A felhasználó megvizsgálhatja az alkalmazást, a kérésfejléceket, a forrástérképeket vagy a hálózati forgalmat, és megszerezheti a kulcsot.

Ha egy webhelynek vagy alkalmazásnak műveletet kell indítania, először küldje el a kérést a saját, hitelesített háttérrendszerének. Ez a háttérrendszer ellenőrizze a felhasználót, majd a szerveren tárolt kulccsal hívja meg a Maildroppát.

A lehető legkisebb kitettséget használja

A kulcsot csak azoknak a rendszereknek adja át, amelyeknek szükségük van rá. Ne ossza meg minden fejlesztővel, és ne illessze be több helyi konfigurációs fájlba.

Mivel az oldal jelenleg egyetlen, teljes fiókra kiterjedő kulcsot kezel több elnevezett vagy hatókörhöz kötött kulcs helyett, használjon belső integrációs szolgáltatást vagy proxyt, ha több alkalmazásnak erősebb elszigetelésre van szüksége egymástól.

Takarja ki a kérésfejléceket

Állítsa be a HTTP-klienseket, fordított proxykat, megfigyelési eszközöket és hibajelentőket az X-API-Key kitakarására. Egy kérés megfelelően működhet úgy is, hogy közben a hitelesítő adat debugnaplókon keresztül kiszivárog.

Tartsa elkülönítve a környezeteket

Ne használjon éles kulcsot helyi fejlesztésben, mintakódban, képernyőképen vagy tesztfájlban. A környezetspecifikus titkos értékeket környezetspecifikus titkostárakban tárolja.

Az „OpenAPI-dokumentáció megtekintése” hivatkozás automatikusan az éles API dokumentációjára irányítja az éles felhasználókat. Valós kulcs küldése előtt mindig ellenőrizze a gépnevet.

Újragenerálás minden gyanús kitettség után

Egy üzenet, verziótári véglegesítés, naplósor vagy képernyőkép törlése nem bizonyítja, hogy senki sem másolta le a kulcsot. Ha a teljes érték illetéktelenekhez kerülhetett, generáljon új kulcsot.

API-hibák kezelése

A HTTP-állapot és a dokumentált válasz törzse alapján döntse el, mit tegyen az integráció.

Gyakori esetek:

• 400 Bad Request — Az útvonal, a paraméter vagy a JSON-törzs nem felel meg a végpont szerződésének. Hasonlítsa össze a kérést az OpenAPI-sémával.
• 401 Unauthorized — Az X-API-Key fejléc hiányzik, üres, érvénytelen vagy törölt kulcsot tartalmaz, illetve újragenerálás után régi értéket használ.
• 403 Forbidden — A hitelesített kulcs nem jogosult a művelet használatára.
• 404 Not Found — Az útvonal vagy a hivatkozott erőforrás nem létezik ebben a fiókban.
• 429 Too Many Requests — Az integráció elérte az API sebességkorlátját. Szüneteltesse a kéréseket, és ha jelen van, tartsa be a Retry-After fejlécet.
• 5xx — A Maildroppa nem tudta befejezni a kérést. A biztonságos műveleteket korlátozott exponenciális visszalépéssel és az API-kulcsot kizáró naplózással próbálja újra.

Ne próbáljon újra vakon minden hibát. Javítsa a 400, 401, 403 és a legtöbb 404 választ, mielőtt ugyanazt a kérést újra elküldi.

Módosító kéréseknél ellenőrizze a végpont újrapróbálkozási és idempotenciaviselkedését, mielőtt automatikusan megismételné a kérést. A kapcsolat megszakadása nem bizonyítja mindig, hogy a Maildroppa nem hajtott végre módosítást.

Hibaelhárítás

Az „API-kulcs létrehozása” továbbra is látható

Jelenleg nincs kulcs a fiókban. Kattintson egyszer a gombra, majd várja meg a kérés befejezését.

Ha a létrehozás sikertelen, töltse újra az oldalt, mielőtt újra próbálkozna. Lehet, hogy egy másik oldal vagy Automatizációs beállítás már létrehozta a fiókkulcsot.

Az oldalon látható kulcs túl rövidnek tűnik

Az oldal szándékosan csak az első öt karaktert és a ***** értéket jeleníti meg. A teljes érték kimásolásához kattintson a „Másolás” gombra. Ne küldje el a maszkolt szöveget kérésben.

A „Másolás” nem vált „Másolva!” feliratra

Lehetséges, hogy a böngésző letiltotta a vágólaphoz való hozzáférést. Tartsa az oldalt aktív lapon, kérés esetén engedélyezze a vágólap-hozzáférést, majd kattintson ismét a „Másolás” gombra.

Ne próbálja meg rekonstruálni a kulcsot a maszkolt szövegből.

Egy kérés 401 Unauthorized választ ad

Ellenőrizze, hogy:

• A fejléc neve pontosan X-API-Key.
• A fejléc a teljes értéket tartalmazza, a látható csillagok nélkül.
• Az integráció nem az Authorization: Bearer fejlécet küldi helyette.
• Nem került szóköz, idézőjel vagy sortörés a titkos értékbe.
• Senki nem generálta újra vagy törölte a fiókkulcsot.
• Újraindították a szolgáltatást, ha az csak induláskor olvassa be a környezeti változókat.
• A kérés a megfelelő Maildroppa API-környezetbe kerül.

Az egyik integráció működik, a másik viszont leállt az újragenerálás után

A második integráció valószínűleg még a régi kulcsot használja. Nincs átfedési időszak. Frissítse a titkos értékét, és indítsa újra a konfigurációt gyorsítótárazó folyamatokat.

Az OpenAPI-oldal működik, de egy végpont 403 választ ad

Nem minden alkalmazásvégpont támogatja az API-kulcsos hitelesítést. Olyan műveletet használjon, amelyet az ügyfél-API dokumentál, és ellenőrizze hitelesítési követelményeit az OpenAPI-oldalon.

A kérések 429 Too Many Requests választ adnak

Csökkentse a kérési rohamokat, helyezze várólistára a munkát, majd próbálkozzon újra az API által visszaadott késleltetés után. Kerülje a párhuzamos újrapróbálkozási viharokat. Ha több alkalmazás osztozik az egyetlen fiókkulcson, hangolja össze kérési mennyiségüket, mert közösen használják a fiók API-korlátait.

Javasolt beállítási ellenőrzőlista

Mielőtt egy integrációt rendszeresen használni kezdene, ellenőrizze, hogy:

• A kulcs kizárólag szerveroldali titkos konfigurációban van tárolva.
• A kérések az X-API-Key fejlécet használják.
• Az integráció éles környezetben a https://api.maildroppa.com címet használja.
• Minden metódus, útvonal, paraméter és JSON-törzs megfelel az OpenAPI-dokumentációnak.
• A naplók és hibajelentések kitakarják a kulcsot.
• Az időkorlátok és a korlátozott újrapróbálkozások be vannak állítva.
• A 401, 403, 429 és szerverhibákat figyelik.
• Rögzítve van az integráció tulajdonosa.
• Minden, a fiókkulcson osztozó rendszer szerepel az újragenerálási tervben.
• Egy kompromittálódott kulcs gyorsan újragenerálható.

Az API-kulcs oldala szándékosan egyszerű, de műveletei a fiókhoz kapcsolódó minden API-integrációt érintenek. Csak akkor hozza létre a kulcsot, amikor szüksége van rá, tartsa megbízható szervereken, és tervezze meg az újragenerálást fiókszintű hitelesítőadat-cseréként.