[{"data":1,"prerenderedAt":588},["ShallowReactive",2],{"search-de":3,"content-de-api\u002Fauthentication":4,"surround-de-\u002Fapi\u002Fauthentication":579},[],{"id":5,"title":6,"body":7,"description":571,"extension":572,"meta":573,"navigation":574,"path":575,"seo":576,"stem":577,"__hash__":578},"content_de\u002F2.api\u002F2.authentication.md","Authentifizierung",{"type":8,"value":9,"toc":553},"minimark",[10,14,19,22,39,43,74,87,91,100,160,166,208,214,256,263,306,313,356,359,375,436,440,447,521,529,533,549],[11,12,13],"p",{},"Sicherer API-Zugriff mit organisationsgebundenen API-Keys. Jedes Deployment bedient genau eine Organisation, daher ist ein Key an diese eine Organisation gebunden und nicht an einen von mehreren Mandanten.",[15,16,18],"h2",{"id":17},"format-des-api-keys","Format des API-Keys",[11,20,21],{},"Owlat validiert Keys anhand eines Live-Präfix-Formats:",[23,24,29],"pre",{"className":25,"code":26,"language":27,"meta":28,"style":28},"language-txt shiki shiki-themes github-light github-dark-dimmed","lm_live_...\n","txt","",[30,31,32],"code",{"__ignoreMap":28},[33,34,37],"span",{"class":35,"line":36},"line",1,[33,38,26],{},[15,40,42],{"id":41},"auth-header-senden","Auth-Header senden",[23,44,48],{"className":45,"code":46,"language":47,"meta":28,"style":28},"language-bash shiki shiki-themes github-light github-dark-dimmed","curl \"https:\u002F\u002F\u003Cdeployment>.convex.site\u002Fapi\u002Fv1\u002Fcontacts\" \\\n  -H \"Authorization: Bearer lm_live_your_key\"\n","bash",[30,49,50,64],{"__ignoreMap":28},[33,51,52,56,60],{"class":35,"line":36},[33,53,55],{"class":54},"sOLd2","curl",[33,57,59],{"class":58},"s-HuK"," \"https:\u002F\u002F\u003Cdeployment>.convex.site\u002Fapi\u002Fv1\u002Fcontacts\"",[33,61,63],{"class":62},"s74oq"," \\\n",[33,65,67,71],{"class":35,"line":66},2,[33,68,70],{"class":69},"sviXB","  -H",[33,72,73],{"class":58}," \"Authorization: Bearer lm_live_your_key\"\n",[11,75,76,79,80,83,84,86],{},[30,77,78],{},"Authorization: \u003Capi_key>"," (ohne ",[30,81,82],{},"Bearer",") wird ebenfalls akzeptiert, empfohlen ist jedoch ",[30,85,82],{},".",[15,88,90],{"id":89},"häufige-auth-fehler","Häufige Auth-Fehler",[92,93,95,96,99],"h3",{"id":94},"fehlender-header-401","Fehlender Header (",[30,97,98],{},"401",")",[23,101,105],{"className":102,"code":103,"language":104,"meta":28,"style":28},"language-json shiki shiki-themes github-light github-dark-dimmed","{\n  \"error\": {\n    \"message\": \"Missing or invalid Authorization header. Use: Authorization: Bearer \u003Capi_key>\",\n    \"category\": \"unauthenticated\"\n  }\n}\n","json",[30,106,107,113,122,137,148,154],{"__ignoreMap":28},[33,108,109],{"class":35,"line":36},[33,110,112],{"class":111},"sYgZi","{\n",[33,114,115,119],{"class":35,"line":66},[33,116,118],{"class":117},"snmFh","  \"error\"",[33,120,121],{"class":111},": {\n",[33,123,125,128,131,134],{"class":35,"line":124},3,[33,126,127],{"class":117},"    \"message\"",[33,129,130],{"class":111},": ",[33,132,133],{"class":58},"\"Missing or invalid Authorization header. Use: Authorization: Bearer \u003Capi_key>\"",[33,135,136],{"class":111},",\n",[33,138,140,143,145],{"class":35,"line":139},4,[33,141,142],{"class":117},"    \"category\"",[33,144,130],{"class":111},[33,146,147],{"class":58},"\"unauthenticated\"\n",[33,149,151],{"class":35,"line":150},5,[33,152,153],{"class":111},"  }\n",[33,155,157],{"class":35,"line":156},6,[33,158,159],{"class":111},"}\n",[92,161,163,164,99],{"id":162},"ungültiges-format-401","Ungültiges Format (",[30,165,98],{},[23,167,169],{"className":102,"code":168,"language":104,"meta":28,"style":28},"{\n  \"error\": {\n    \"message\": \"Invalid API key format\",\n    \"category\": \"unauthenticated\"\n  }\n}\n",[30,170,171,175,181,192,200,204],{"__ignoreMap":28},[33,172,173],{"class":35,"line":36},[33,174,112],{"class":111},[33,176,177,179],{"class":35,"line":66},[33,178,118],{"class":117},[33,180,121],{"class":111},[33,182,183,185,187,190],{"class":35,"line":124},[33,184,127],{"class":117},[33,186,130],{"class":111},[33,188,189],{"class":58},"\"Invalid API key format\"",[33,191,136],{"class":111},[33,193,194,196,198],{"class":35,"line":139},[33,195,142],{"class":117},[33,197,130],{"class":111},[33,199,147],{"class":58},[33,201,202],{"class":35,"line":150},[33,203,153],{"class":111},[33,205,206],{"class":35,"line":156},[33,207,159],{"class":111},[92,209,211,212,99],{"id":210},"ungültiger-oder-widerrufener-key-401","Ungültiger oder widerrufener Key (",[30,213,98],{},[23,215,217],{"className":102,"code":216,"language":104,"meta":28,"style":28},"{\n  \"error\": {\n    \"message\": \"Invalid API key\",\n    \"category\": \"unauthenticated\"\n  }\n}\n",[30,218,219,223,229,240,248,252],{"__ignoreMap":28},[33,220,221],{"class":35,"line":36},[33,222,112],{"class":111},[33,224,225,227],{"class":35,"line":66},[33,226,118],{"class":117},[33,228,121],{"class":111},[33,230,231,233,235,238],{"class":35,"line":124},[33,232,127],{"class":117},[33,234,130],{"class":111},[33,236,237],{"class":58},"\"Invalid API key\"",[33,239,136],{"class":111},[33,241,242,244,246],{"class":35,"line":139},[33,243,142],{"class":117},[33,245,130],{"class":111},[33,247,147],{"class":58},[33,249,250],{"class":35,"line":150},[33,251,153],{"class":111},[33,253,254],{"class":35,"line":156},[33,255,159],{"class":111},[92,257,259,260,99],{"id":258},"unzureichender-scope-403","Unzureichender Scope (",[30,261,262],{},"403",[23,264,266],{"className":102,"code":265,"language":104,"meta":28,"style":28},"{\n  \"error\": {\n    \"message\": \"This API key is missing the required scope: contacts:write\",\n    \"category\": \"forbidden\"\n  }\n}\n",[30,267,268,272,278,289,298,302],{"__ignoreMap":28},[33,269,270],{"class":35,"line":36},[33,271,112],{"class":111},[33,273,274,276],{"class":35,"line":66},[33,275,118],{"class":117},[33,277,121],{"class":111},[33,279,280,282,284,287],{"class":35,"line":124},[33,281,127],{"class":117},[33,283,130],{"class":111},[33,285,286],{"class":58},"\"This API key is missing the required scope: contacts:write\"",[33,288,136],{"class":111},[33,290,291,293,295],{"class":35,"line":139},[33,292,142],{"class":117},[33,294,130],{"class":111},[33,296,297],{"class":58},"\"forbidden\"\n",[33,299,300],{"class":35,"line":150},[33,301,153],{"class":111},[33,303,304],{"class":35,"line":156},[33,305,159],{"class":111},[92,307,309,310,99],{"id":308},"rate-limit-überschritten-429","Rate-Limit überschritten (",[30,311,312],{},"429",[23,314,316],{"className":102,"code":315,"language":104,"meta":28,"style":28},"{\n  \"error\": {\n    \"message\": \"Rate limit exceeded. Maximum 10 requests per second.\",\n    \"category\": \"rate_limited\"\n  }\n}\n",[30,317,318,322,328,339,348,352],{"__ignoreMap":28},[33,319,320],{"class":35,"line":36},[33,321,112],{"class":111},[33,323,324,326],{"class":35,"line":66},[33,325,118],{"class":117},[33,327,121],{"class":111},[33,329,330,332,334,337],{"class":35,"line":124},[33,331,127],{"class":117},[33,333,130],{"class":111},[33,335,336],{"class":58},"\"Rate limit exceeded. Maximum 10 requests per second.\"",[33,338,136],{"class":111},[33,340,341,343,345],{"class":35,"line":139},[33,342,142],{"class":117},[33,344,130],{"class":111},[33,346,347],{"class":58},"\"rate_limited\"\n",[33,349,350],{"class":35,"line":150},[33,351,153],{"class":111},[33,353,354],{"class":35,"line":156},[33,355,159],{"class":111},[11,357,358],{},"Das Limit ist ein Token-Bucket, der dauerhaft 10 Anfragen pro Sekunde trägt, kurze Bursts von bis zu 15 Anfragen aber zulässt, bevor gedrosselt wird.",[11,360,361,362,364,365,367,368,371,372,374],{},"Authentifizierte Antworten (einschließlich der ",[30,363,312],{}," selbst) enthalten Rate-Limit-Header, damit Clients präzise zurückregeln können. Eine ",[30,366,312],{}," enthält zusätzlich ",[30,369,370],{},"Retry-After",". Authentifizierungsfehler (",[30,373,98],{},") enthalten diese Header nicht.",[376,377,378,391],"table",{},[379,380,381],"thead",{},[382,383,384,388],"tr",{},[385,386,387],"th",{},"Header",[385,389,390],{},"Bedeutung",[392,393,394,405,415,425],"tbody",{},[382,395,396,402],{},[397,398,399],"td",{},[30,400,401],{},"X-RateLimit-Limit",[397,403,404],{},"Dauerhaft zulässige Anfragen pro Sekunde",[382,406,407,412],{},[397,408,409],{},[30,410,411],{},"X-RateLimit-Remaining",[397,413,414],{},"Im aktuellen Fenster verbleibende Anfragen",[382,416,417,422],{},[397,418,419],{},[30,420,421],{},"X-RateLimit-Reset",[397,423,424],{},"Unix-Zeitstempel (Sekunden), zu dem das Fenster zurückgesetzt wird",[382,426,427,431],{},[397,428,429],{},[30,430,370],{},[397,432,433,434,99],{},"Wartezeit in Sekunden vor einem erneuten Versuch (nur bei ",[30,435,312],{},[15,437,439],{"id":438},"scopes","Scopes",[11,441,442,443,446],{},"Jeder Key trägt eine Menge von Scopes, die festlegen, welche v1-Endpunkte er aufrufen darf. Eine Anfrage mit einem Key, dem der erforderliche Scope fehlt, wird mit ",[30,444,445],{},"403 forbidden"," abgelehnt (siehe oben).",[376,448,449,459],{},[379,450,451],{},[382,452,453,456],{},[385,454,455],{},"Scope",[385,457,458],{},"Erlaubt",[392,460,461,477,487,499,511],{},[382,462,463,468],{},[397,464,465],{},[30,466,467],{},"contacts:read",[397,469,470,473,474],{},[30,471,472],{},"GET \u002Fapi\u002Fv1\u002Fcontacts",", ",[30,475,476],{},"GET \u002Fapi\u002Fv1\u002Fcontacts\u002F{id}",[382,478,479,484],{},[397,480,481],{},[30,482,483],{},"contacts:write",[397,485,486],{},"Kontakte anlegen \u002F aktualisieren \u002F löschen",[382,488,489,494],{},[397,490,491],{},[30,492,493],{},"events:write",[397,495,496],{},[30,497,498],{},"POST \u002Fapi\u002Fv1\u002Fevents",[382,500,501,506],{},[397,502,503],{},[30,504,505],{},"transactional:send",[397,507,508],{},[30,509,510],{},"POST \u002Fapi\u002Fv1\u002Ftransactional",[382,512,513,518],{},[397,514,515],{},[30,516,517],{},"topics:write",[397,519,520],{},"einen Kontakt zu einem Thema hinzufügen \u002F entfernen",[11,522,523,524,528],{},"Das Anlegen eines Keys ",[525,526,527],"strong",{},"erfordert"," eine explizite, nicht leere Scope-Liste — wird sie weggelassen, wird die Anfrage abgelehnt, und unbekannte Scope-Namen werden ebenfalls abgelehnt. Bereits vorhandene Keys ohne gespeicherte Scopes werden so behandelt, als hätten sie keine (Deny-all); vergeben Sie daher gezielt die Scopes, die jede Integration benötigt.",[15,530,532],{"id":531},"best-practices","Best Practices",[534,535,536,540,543,546],"ul",{},[537,538,539],"li",{},"Keys ausschließlich serverseitig halten",[537,541,542],{},"Keys planmäßig rotieren und widerrufen",[537,544,545],{},"Pro Umgebung eigene Keys verwenden",[537,547,548],{},"Anfragemuster und Fehler überwachen",[550,551,552],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sOLd2, html code.shiki .sOLd2{--shiki-default:#6F42C1;--shiki-dark:#F69D50}html pre.shiki code .s-HuK, html code.shiki .s-HuK{--shiki-default:#032F62;--shiki-dark:#96D0FF}html pre.shiki code .s74oq, html code.shiki .s74oq{--shiki-default:#005CC5;--shiki-dark:#F47067}html pre.shiki code .sviXB, html code.shiki .sviXB{--shiki-default:#005CC5;--shiki-dark:#6CB6FF}html pre.shiki code .sYgZi, html code.shiki .sYgZi{--shiki-default:#24292E;--shiki-dark:#ADBAC7}html pre.shiki code .snmFh, html code.shiki .snmFh{--shiki-default:#005CC5;--shiki-dark:#8DDB8C}",{"title":28,"searchDepth":66,"depth":66,"links":554},[555,556,557,569,570],{"id":17,"depth":66,"text":18},{"id":41,"depth":66,"text":42},{"id":89,"depth":66,"text":90,"children":558},[559,561,563,565,567],{"id":94,"depth":124,"text":560},"Fehlender Header (401)",{"id":162,"depth":124,"text":562},"Ungültiges Format (401)",{"id":210,"depth":124,"text":564},"Ungültiger oder widerrufener Key (401)",{"id":258,"depth":124,"text":566},"Unzureichender Scope (403)",{"id":308,"depth":124,"text":568},"Rate-Limit überschritten (429)",{"id":438,"depth":66,"text":439},{"id":531,"depth":66,"text":532},"Sicherer API-Zugriff mit organisationsgebundenen API-Keys.","md",{},true,"\u002Fapi\u002Fauthentication",{"title":6,"description":571},"2.api\u002F2.authentication","7aw_cR7ePHmIzTIFgeeY8zvdEW36V_NLZzLULCaBcBI",[580,584],{"title":581,"path":582,"stem":583,"children":-1},"Webhooks für eingehende Kanäle","\u002Fapi\u002Finbound-channels","2.api\u002F13.inbound-channels",{"title":585,"path":586,"stem":587,"children":-1},"TypeScript-SDK","\u002Fapi\u002Fsdk","2.api\u002F3.sdk",1786915106623]