API-Übersicht
Dieser Referenzartikel behandelt die API-Grundlagen, einschließlich gängiger Terminologie und einer Übersicht über REST-API-Schlüssel, Berechtigungen und deren Sicherheit.
Braze REST API-Sammlung
| Sammlung | Zweck |
|---|---|
| Kataloge | Erstellen und verwalten Sie Kataloge und Katalogartikel zur Referenzierung in Ihren Braze-Campaigns. |
| Cloud-Datenaufnahme | Verwalten Sie Ihre Data-Warehouse-Integrationen und -Synchronisierungen. |
| E-Mail-Listen und -Adressen | Richten Sie eine bidirektionale Synchronisierung zwischen Braze und Ihren E-Mail-Systemen ein und verwalten Sie diese. |
| Export | Greifen Sie auf verschiedene Details Ihrer Campaigns, Canvases, KPIs und mehr zu und exportieren Sie diese. |
| Medienbibliothek | Verwalten Sie Assets in Braze. |
| Nachrichten | Planen, senden und verwalten Sie Ihre Campaigns und Canvases. |
| Einstellungscenter | Erstellen Sie Ihr Einstellungscenter und aktualisieren Sie dessen Gestaltung. |
| SCIM | Verwalten Sie Nutzeridentitäten in cloudbasierten Anwendungen und Diensten. |
| SMS | Verwalten Sie die Telefonnummern Ihrer Nutzer:innen in Ihren Abo-Gruppen. |
| Abo-Gruppen | Listen und aktualisieren Sie sowohl SMS- als auch E-Mail-Abo-Gruppen, die im Braze-Dashboard gespeichert sind. |
| Templates | Erstellen und aktualisieren Sie Templates für E-Mail-Messaging und Content Blocks. |
| Nutzerdaten | Identifizieren, verfolgen und verwalten Sie Ihre Nutzer:innen. |
API-Definitionen
Im Folgenden finden Sie eine Übersicht über Begriffe, die in der Braze-REST-API-Dokumentation vorkommen können.
Endpunkte
Braze betreibt eine Reihe verschiedener Instanzen für unser Dashboard und unsere REST-Endpunkte. Wenn Ihr Konto bereitgestellt wird, melden Sie sich bei einer der folgenden URLs an. Verwenden Sie den richtigen REST-Endpunkt basierend auf der Instanz, der Sie zugewiesen sind. Wenn Sie sich nicht sicher sind, eröffnen Sie ein Support-Ticket oder verwenden Sie die folgende Tabelle, um die URL des von Ihnen genutzten Dashboards dem richtigen REST-Endpunkt zuzuordnen.
So finden Sie Ihren REST-Endpunkt in Braze:
- Melden Sie sich bei Braze an und navigieren Sie zu Einstellungen > APIs und Bezeichner > API-Schlüssel.
- Wählen Sie einen vorhandenen API-Schlüssel aus oder wählen Sie API-Schlüssel erstellen, um einen neuen Schlüssel zu erstellen.
- Kopieren Sie den auf diesem Tab angezeigten REST-Endpunkt und verwenden Sie diesen Endpunkt für Ihre API-Anfragen.
Wenn Sie Endpunkte für API-Aufrufe verwenden, nutzen Sie den REST-Endpunkt.
Für die SDK-Integration verwenden Sie den SDK-Endpunkt, nicht den REST-Endpunkt.
| Instanz | URL | REST-Endpunkt | SDK-Endpunkt |
|---|---|---|---|
| US-01 | https://dashboard-01.braze.com |
https://rest.iad-01.braze.com |
sdk.iad-01.braze.com |
| US-02 | https://dashboard-02.braze.com |
https://rest.iad-02.braze.com |
sdk.iad-02.braze.com |
| US-03 | https://dashboard-03.braze.com |
https://rest.iad-03.braze.com |
sdk.iad-03.braze.com |
| US-04 | https://dashboard-04.braze.com |
https://rest.iad-04.braze.com |
sdk.iad-04.braze.com |
| US-05 | https://dashboard-05.braze.com |
https://rest.iad-05.braze.com |
sdk.iad-05.braze.com |
| US-06 | https://dashboard-06.braze.com |
https://rest.iad-06.braze.com |
sdk.iad-06.braze.com |
| US-07 | https://dashboard-07.braze.com |
https://rest.iad-07.braze.com |
sdk.iad-07.braze.com |
| US-08 | https://dashboard-08.braze.com |
https://rest.iad-08.braze.com |
sdk.iad-08.braze.com |
| US-10 | https://dashboard.us-10.braze.com |
https://rest.us-10.braze.com |
sdk.us-10.braze.com |
| EU-01 | https://dashboard-01.braze.eu |
https://rest.fra-01.braze.eu |
sdk.fra-01.braze.eu |
| EU-02 | https://dashboard-02.braze.eu |
https://rest.fra-02.braze.eu |
sdk.fra-02.braze.eu |
| AU-01 | https://dashboard.au-01.braze.com |
https://rest.au-01.braze.com |
sdk.au-01.braze.com |
| ID-01 | https://dashboard.id-01.braze.com |
https://rest.id-01.braze.com |
sdk.id-01.braze.com |
| JP-01 | https://dashboard.jp-01.braze.com |
https://rest.jp-01.braze.com |
sdk.jp-01.braze.com |
| KR-01 | https://dashboard.kr-01.braze.com |
https://rest.kr-01.braze.com |
sdk.kr-01.braze.com |
API-Limits
Für die meisten APIs hat Braze ein standardmäßiges Rate-Limit von 250.000 Anfragen pro Stunde. Bestimmte Anfragetypen haben jedoch ein eigenes Rate-Limit, um große Datenmengen über die gesamte Kundenbasis hinweg besser verarbeiten zu können. Weitere Informationen finden Sie unter API-Rate-Limits.
Nutzer-IDs
- Externe Nutzer-ID: Die
external_iddient als eindeutiger Bezeichner für die Nutzer:innen, für die Sie Daten übermitteln. Dieser Bezeichner sollte derselbe sein, den Sie im Braze SDK festgelegt haben, um die Erstellung mehrerer Profile für dieselbe Person zu vermeiden. - Braze-Nutzer-ID: Die
braze_iddient als eindeutiger Bezeichner für Nutzer:innen, der von Braze vergeben wird. Sie können diesen Bezeichner verwenden, um Nutzer:innen über die REST API zusätzlich zu external_ids zu löschen.
Weitere Informationen finden Sie in den folgenden Artikeln je nach Ihrer Plattform: iOS, Android und Web.
Über REST-API-Schlüssel
Ein REST-API-Schlüssel (REST Application Programming Interface Key) ist ein eindeutiger Code, den Sie an eine API übergeben, um den API-Aufruf zu authentifizieren und die aufrufende Anwendung oder den aufrufenden Nutzer:in zu identifizieren. Sie greifen über HTTPS-Webanfragen an den REST-API-Endpunkt Ihres Unternehmens auf die API zu. REST-API-Schlüssel arbeiten zusammen mit App-Bezeichner-Schlüsseln, um Daten zu verfolgen, darauf zuzugreifen, zu senden, zu exportieren und zu analysieren – damit alles reibungslos läuft.
Workspaces und API-Schlüssel sind bei Braze eng miteinander verknüpft. Workspaces sind dafür konzipiert, Versionen derselben Anwendung über mehrere Plattformen hinweg zu verwalten. Viele Kund:innen nutzen Workspaces auch, um kostenlose und Premium-Versionen ihrer Anwendungen auf derselben Plattform bereitzustellen. Wie Sie vielleicht bemerken, nutzen diese Workspaces ebenfalls die REST API und verfügen über eigene REST-API-Schlüssel. Diese Schlüssel können individuell so konfiguriert werden, dass sie nur Zugriff auf bestimmte Endpunkte der API gewähren. Jeder API-Aufruf muss einen Schlüssel mit Zugriff auf den angesprochenen Endpunkt enthalten.
Wir bezeichnen sowohl den REST-API-Schlüssel als auch den Workspace-API-Schlüssel als api_key. Der api_key wird bei jeder Anfrage als Anfrage-Header mitgesendet und dient als Authentifizierungsschlüssel, der Ihnen die Nutzung unserer REST APIs ermöglicht. Diese REST APIs werden verwendet, um Nutzer:innen zu tracken, Nachrichten zu senden, Nutzerdaten zu exportieren und mehr. Wenn Sie einen neuen REST-API-Schlüssel erstellen, müssen Sie ihm Zugriff auf bestimmte Endpunkte gewähren. Indem Sie einem API-Schlüssel spezifische Berechtigungen zuweisen, können Sie genau einschränken, welche Aufrufe ein API-Schlüssel authentifizieren kann.
Neben REST-API-Schlüsseln gibt es auch sogenannte Bezeichner-Schlüssel, die verwendet werden können, um bestimmte Objekte wie Apps, Templates, Canvases, Campaigns, Content Cards und Segments über die API zu referenzieren. Weitere Informationen finden Sie unter API-Bezeichnertypen.
REST-API-Schlüssel erstellen
So erstellen Sie einen neuen REST-API-Schlüssel:
- Gehen Sie zu Einstellungen > APIs und Bezeichner.
- Wählen Sie API-Schlüssel erstellen.
- Geben Sie Ihrem neuen Schlüssel einen Namen zur schnellen Identifikation.
- Legen Sie erlaubte IP-Adressen und Subnetze für den neuen Schlüssel fest.
- Wählen Sie aus, welche Berechtigungen mit Ihrem neuen Schlüssel verknüpft werden sollen.
Beachten Sie, dass Sie nach dem Erstellen eines neuen API-Schlüssels den Berechtigungsumfang oder die erlaubten IPs nicht mehr bearbeiten können. Diese Einschränkung besteht aus Sicherheitsgründen. Wenn Sie den Umfang eines Schlüssels ändern müssen, erstellen Sie einen neuen Schlüssel mit den aktualisierten Berechtigungen und implementieren Sie diesen anstelle des alten Schlüssels. Nachdem Sie die Implementierung abgeschlossen haben, können Sie den alten Schlüssel löschen.
Berechtigungen für REST-API-Schlüssel
API-Schlüsselberechtigungen sind Berechtigungen, die Sie einem Nutzer:in oder einer Gruppe zuweisen können, um den Zugriff auf bestimmte API-Aufrufe einzuschränken. Um Ihre Liste der API-Schlüsselberechtigungen anzuzeigen, gehen Sie zu Einstellungen > APIs und Bezeichner und wählen Sie Ihren API-Schlüssel aus.
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
users.track |
/users/track |
Nutzerattribute, angepasste Events und Käufe aufzeichnen. |
users.track.status |
/users/track/status |
Den Verarbeitungsstatus für eine Gruppe asynchroner /users/track-Anfragen abrufen. |
users.delete |
/users/delete |
Beliebige:n Nutzer:in löschen. |
users.alias.new |
/users/alias/new |
Einen neuen Alias für eine:n bestehende:n Nutzer:in erstellen. |
users.identify |
/users/identify |
Eine:n Nur-Alias-Nutzer:in mit einer externen ID identifizieren. |
users.export.ids |
/users/export/ids |
Nutzerprofilinformationen nach Nutzer-ID abfragen. |
users.export.segment |
/users/export/segment |
Nutzerprofilinformationen nach Segment abfragen. |
users.merge |
/users/merge |
Zwei bestehende Nutzer:innen zusammenführen. |
users.external_ids.rename |
/users/external_ids/rename |
Die externe ID für eine:n bestehende:n Nutzer:in ändern. |
users.external_ids.remove |
/users/external_ids/remove |
Die externe ID für eine:n bestehende:n Nutzer:in entfernen. |
users.alias.update |
/users/alias/update |
Einen Alias für eine:n bestehende:n Nutzer:in aktualisieren. |
users.export.global_control_group |
/users/export/global_control_group |
Nutzerprofilinformationen in der globalen Kontrollgruppe abfragen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
email.unsubscribe |
/email/unsubscribes |
Abgemeldete E-Mail-Adressen abfragen. |
email.status |
/email/status |
E-Mail-Adressstatus ändern. |
email.hard_bounces |
/email/hard_bounces |
Hard-Bounce-E-Mail-Adressen abfragen. |
email.bounce.remove |
/email/bounce/remove |
E-Mail-Adressen von Ihrer Hard-Bounce-Liste entfernen. |
email.spam.remove |
/email/spam/remove |
E-Mail-Adressen von Ihrer Spam-Liste entfernen. |
email.blacklist |
/email/blacklist |
E-Mail-Adressen auf die Sperrliste setzen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
campaigns.trigger.send |
/campaigns/trigger/send |
Den Versand einer bestehenden Campaign auslösen. |
campaigns.trigger.schedule.create |
/campaigns/trigger/schedule/create |
Einen Versand einer Campaign mit API-gesteuerter Zustellung planen. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Eine Campaign mit API-gesteuerter Zustellung aktualisieren. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Eine Campaign mit API-gesteuerter Zustellung löschen. |
campaigns.list |
/campaigns/list |
Eine Liste von Campaigns abfragen. |
campaigns.data_series |
/campaigns/data_series |
Campaign-Analytics über einen Zeitraum abfragen. |
campaigns.details |
/campaigns/details |
Details einer bestimmten Campaign abfragen. |
sends.data_series |
/sends/data_series |
Nachrichtenversand-Analytics über einen Zeitraum abfragen. |
sends.id.create |
/sends/id/create |
Eine Sende-ID für das Tracking von Massennachrichten erstellen. |
campaigns.url_info.details |
/campaigns/url_info/details |
URL-Details einer bestimmten Nachrichtenvariante innerhalb einer Campaign abfragen. Diese Berechtigung ist nur für Workspaces verfügbar, in denen Link Aliasing aktiviert ist. Wenn diese Berechtigung in Ihrem Workspace nicht verfügbar ist, wenden Sie sich an Ihren Braze Account Manager. |
transactional.send |
/transactional/v1/campaigns/{campaign_id}/send |
Ermöglicht den Versand von Transaktionsnachrichten über den Transaktionsnachrichten-Endpunkt. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
canvas.trigger.send |
/canvas/trigger/send |
Den Versand eines bestehenden Canvas auslösen. |
canvas.trigger.schedule.create |
/canvas/trigger/schedule/create |
Einen Versand eines Canvas mit API-gesteuerter Zustellung planen. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Einen Canvas mit API-gesteuerter Zustellung aktualisieren. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Einen Canvas mit API-gesteuerter Zustellung löschen. |
canvas.list |
/canvas/list |
Eine Liste von Canvases abfragen. |
canvas.data_series |
/canvas/data_series |
Canvas-Analytics über einen Zeitraum abfragen. |
canvas.details |
/canvas/details |
Details eines bestimmten Canvas abfragen. |
canvas.data_summary |
/canvas/data_summary |
Zusammenfassungen der Canvas-Analytics über einen Zeitraum abfragen. |
canvas.url_info.details |
/canvas/url_info/details |
URL-Details einer bestimmten Nachrichtenvariante innerhalb eines Canvas-Schritts abfragen. Diese Berechtigung ist nur für Workspaces verfügbar, in denen Link Aliasing aktiviert ist. Wenn diese Berechtigung in Ihrem Workspace nicht verfügbar ist, wenden Sie sich an Ihren Braze Account Manager. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
segments.list |
/segments/list |
Eine Liste von Segments abfragen. |
segments.data_series |
/segments/data_series |
Segment-Analytics über einen Zeitraum abfragen. |
segments.details |
/segments/details |
Details eines bestimmten Segments abfragen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
purchases.product_list |
/purchases/product_list |
Eine Liste der in Ihrer App gekauften Produkte abfragen. |
purchases.revenue_series |
/purchases/revenue_series |
Den Gesamtumsatz pro Tag in Ihrer App über einen Zeitraum abfragen. |
purchases.quantity_series |
/purchases/quantity_series |
Die Gesamtanzahl der Käufe pro Tag in Ihrer App über einen Zeitraum abfragen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
events.list |
/events/list |
Eine Liste angepasster Events abfragen. |
events.data_series |
/events/data_series |
Vorkommen eines angepassten Events über einen Zeitraum abfragen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sessions.data_series |
/sessions/data_series |
Sitzungen pro Tag über einen Zeitraum abfragen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
kpi.dau.data_series |
/kpi/dau/data_series |
Eindeutige aktive Nutzer:innen pro Tag über einen Zeitraum abfragen. |
kpi.mau.data_series |
/kpi/mau/data_series |
Gesamtzahl eindeutiger aktiver Nutzer:innen über ein rollierendes 30-Tage-Fenster über einen Zeitraum abfragen. |
kpi.new_users.data_series |
/kpi/new_users/data_series |
Neue Nutzer:innen pro Tag über einen Zeitraum abfragen. |
kpi.uninstalls.data_series |
/kpi/uninstalls/data_series |
App-Deinstallationen pro Tag über einen Zeitraum abfragen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
templates.email.create |
/templates/email/create |
Ein neues E-Mail-Template im Dashboard erstellen. |
templates.email.info |
/templates/email/info |
Informationen zu einem bestimmten Template abfragen. |
templates.email.list |
/templates/email/list |
Eine Liste von E-Mail-Templates abfragen. |
templates.email.update |
/templates/email/update |
Ein im Dashboard gespeichertes E-Mail-Template aktualisieren. |
| Berechtigung | Beschreibung |
|---|---|
sso.saml.login |
Identitätsanbieter-initiierte Anmeldung einrichten. Weitere Informationen finden Sie unter Service-Provider (SP)-initiierte Anmeldung. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
content_blocks.info |
/content_blocks/info |
Informationen zu einem bestimmten Template abfragen. |
content_blocks.list |
/content_blocks/list |
Eine Liste von Content Blocks abfragen. |
content_blocks.create |
/content_blocks/create |
Einen neuen Content-Block im Dashboard erstellen. |
content_blocks.update |
/content_blocks_update |
Einen bestehenden Content-Block im Dashboard aktualisieren. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
preference_center.get |
/preference_center/v1/{preferenceCenterExternalId} |
Ein Präferenzcenter abrufen. |
preference_center.list |
/preference_center/v1/list |
Präferenzcenter auflisten. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Ein Präferenzcenter erstellen oder aktualisieren. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Einen Präferenzcenter-Link für eine:n Nutzer:in abrufen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
subscription.status.set |
/subscription/status/set |
Abo-Gruppenstatus festlegen. |
subscription.status.get |
/subscription/status/get |
Abo-Gruppenstatus abrufen. |
subscription.groups.get |
/subscription/user/status |
Den Status von Abo-Gruppen abrufen, für die bestimmte Nutzer:innen explizit angemeldet oder abgemeldet sind. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sms.invalid_phone_numbers |
/sms/invalid_phone_numbers |
Ungültige Telefonnummern abfragen. |
sms.invalid_phone_numbers.remove |
/sms/invalid_phone_numbers/remove |
Die Markierung als ungültige Telefonnummer für Nutzer:innen entfernen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
catalogs.add_items |
/catalogs/{catalog_name}/items |
Mehrere Artikel zu einem bestehenden Katalog hinzufügen. |
catalogs.update_items |
/catalogs/{catalog_name}/items |
Mehrere Artikel in einem bestehenden Katalog aktualisieren. |
catalogs.delete_items |
/catalogs/{catalog_name}/items |
Mehrere Artikel aus einem bestehenden Katalog löschen. |
catalogs.get_item |
/catalogs/{catalog_name}/items/{item_id} |
Einen einzelnen Artikel aus einem bestehenden Katalog abrufen. |
catalogs.update_item |
/catalogs/{catalog_name}/items/{item_id} |
Einen einzelnen Artikel in einem bestehenden Katalog aktualisieren. |
catalogs.create_item |
/catalogs/{catalog_name}/items/{item_id} |
Einen einzelnen Artikel in einem bestehenden Katalog erstellen. |
catalogs.delete_item |
/catalogs/{catalog_name}/items/{item_id} |
Einen einzelnen Artikel aus einem bestehenden Katalog löschen. |
catalogs.replace_item |
/catalogs/{catalog_name}/items/{item_id} |
Einen einzelnen Artikel in einem bestehenden Katalog ersetzen. |
catalogs.create |
/catalogs |
Einen Katalog erstellen. |
catalogs.get |
/catalogs |
Eine Liste von Katalogen abrufen. |
catalogs.delete |
/catalogs/{catalog_name} |
Einen Katalog löschen. |
catalogs.get_items |
/catalogs/{catalog_name}/items |
Eine Artikelvorschau aus einem bestehenden Katalog abrufen. |
catalogs.replace_items |
/catalogs/{catalog_name}/items |
Artikel in einem bestehenden Katalog ersetzen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sdk_authentication.create |
/app_group/sdk_authentication/create |
Einen neuen SDK-Authentifizierungsschlüssel für Ihre App erstellen. |
sdk_authentication.primary |
/app_group/sdk_authentication/primary |
Einen SDK-Authentifizierungsschlüssel als primären Schlüssel für Ihre App festlegen. |
sdk_authentication.delete |
/app_group/sdk_authentication/delete |
Einen SDK-Authentifizierungsschlüssel für Ihre App löschen. |
sdk_authentication.keys |
/app_group/sdk_authentication/keys |
Alle SDK-Authentifizierungsschlüssel für Ihre App abrufen. |
REST-API-Schlüssel verwalten
Sie können Details bestehender REST-API-Schlüssel anzeigen oder sie löschen, indem Sie zu Einstellungen > APIs und Bezeichner > Tab API Keys navigieren. Beachten Sie, dass Sie REST-API-Schlüssel nach ihrer Erstellung nicht mehr bearbeiten können.
Der Tab API Keys enthält die folgenden Informationen für jeden Schlüssel:
| Feld | Beschreibung |
|---|---|
| API-Schlüsselname | Der Name, der dem Schlüssel bei der Erstellung gegeben wurde. |
| Bezeichner | Der API-Schlüssel. |
| Erstellt von | Die E-Mail-Adresse des/der Nutzer:in, der/die den Schlüssel erstellt hat. Dieses Feld zeigt „N/A“ für Schlüssel an, die vor Juni 2023 erstellt wurden. |
| Erstellungsdatum | Das Datum, an dem dieser Schlüssel erstellt wurde. |
| Zuletzt gesehen | Das Datum, an dem dieser Schlüssel zuletzt verwendet wurde. Dieses Feld zeigt „N/A“ für Schlüssel an, die noch nie verwendet wurden. |
Um die Details eines API-Schlüssels anzuzeigen, bewegen Sie den Mauszeiger über den Schlüssel und wählen Sie Anzeigen. Dies umfasst alle Berechtigungen dieses Schlüssels, freigegebene IPs (falls vorhanden) und ob dieser Schlüssel für die Braze-IP-Freigabeliste aktiviert ist.
Beachten Sie, dass beim Löschen einer:s Nutzer:in Braze die zugehörigen API-Schlüssel, die diese:r Nutzer:in erstellt hat, nicht löscht. Um einen Schlüssel zu löschen, bewegen Sie den Mauszeiger über den Schlüssel und wählen Sie Löschen.
Sicherheit von REST-API-Schlüsseln
API-Schlüssel werden verwendet, um einen API-Aufruf zu authentifizieren. Wenn Sie einen neuen REST-API-Schlüssel erstellen, müssen Sie ihm Zugriff auf bestimmte Endpunkte gewähren. Indem Sie einem API-Schlüssel spezifische Berechtigungen zuweisen, können Sie genau einschränken, welche Aufrufe ein API-Schlüssel authentifizieren kann.
Da REST-API-Schlüssel Zugriff auf potenziell sensible REST-API-Endpunkte ermöglichen, sichern Sie diese Schlüssel und teilen Sie sie nur mit vertrauenswürdigen Partnern. Sie sollten niemals öffentlich zugänglich gemacht werden. Verwenden Sie diesen Schlüssel beispielsweise nicht für AJAX-Aufrufe von Ihrer Website oder stellen Sie ihn anderweitig öffentlich zur Verfügung.
Eine bewährte Sicherheitspraxis besteht darin, Nutzer:innen nur so viel Zugriff zu gewähren, wie für ihre Arbeit erforderlich ist. Dieses Prinzip kann auch auf API-Schlüssel angewendet werden, indem Sie jedem Schlüssel entsprechende Berechtigungen zuweisen. Diese Berechtigungen bieten Ihnen bessere Sicherheit und Kontrolle über die verschiedenen Bereiche Ihres Kontos.
Da REST-API-Schlüssel Zugriff auf potenziell sensible REST-API-Endpunkte ermöglichen, stellen Sie sicher, dass sie sicher gespeichert und verwendet werden. Verwenden Sie diesen Schlüssel beispielsweise nicht für AJAX-Aufrufe von Ihrer Website oder stellen Sie ihn anderweitig öffentlich zur Verfügung.
Wenn Sie versehentlich einen Schlüssel offenlegen, können Sie ihn in der Entwicklungskonsole löschen. Wenn Sie Hilfe bei diesem Vorgang benötigen, eröffnen Sie ein Support-Ticket.
Sicherheit von REST-API-Schlüsseln und SDK-API-Schlüsseln
REST-API-Schlüssel und SDK-API-Schlüssel haben unterschiedliche Sicherheitsprofile.
| Attribut | REST-API-Schlüssel | SDK-API-Schlüssel |
|---|---|---|
| Zweck | Serverseitige Authentifizierung für die REST API (Nachrichten senden, Daten exportieren, Nutzer:innen verwalten) | Clientseitige Identifikation für das Braze SDK (Datenaufnahme, In-App-Nachrichten, Content Cards) |
| Sichtbarkeit | Muss privat bleiben. Niemals in clientseitigem Code, öffentlichen Repositories oder Nutzeranwendungen offenlegen. | Dafür konzipiert, öffentlich zu sein. Wird in der App-Binary gebündelt oder ist im Webbrowser-JavaScript sichtbar, ähnlich wie eine Google-Analytics-Tracking-ID. |
| Lösung bei Offenlegung | Den Schlüssel sofort widerrufen und einen Ersatz unter Einstellungen > APIs und Bezeichner > API Keys erstellen. Ein offengelegter REST-API-Schlüssel kann verwendet werden, um Nachrichten zu senden, Nutzerdaten zu exportieren oder Kontoeinstellungen zu ändern. | Keine Maßnahme erforderlich. Ein SDK-API-Schlüssel kann nur Daten aufnehmen und clientseitige Nachrichten abrufen (wie In-App-Nachrichten und Content Cards). Er kann keine Nutzerdaten exportieren, Nachrichten in Ihrem Namen senden oder Campaigns ändern. |
IP-Freigabeliste für die API
Für zusätzliche Sicherheit können Sie eine Liste von IP-Adressen und Subnetzen angeben, die REST-API-Anfragen für einen bestimmten REST-API-Schlüssel senden dürfen. Dies wird als Allowlisting oder Whitelisting bezeichnet. Um bestimmte IP-Adressen oder Subnetze zuzulassen, fügen Sie sie beim Erstellen eines neuen REST-API-Schlüssels im Abschnitt Whitelist IPs hinzu:
Wenn Sie keine angeben, können Anfragen von jeder IP-Adresse gesendet werden.
Wenn Sie einen Braze-zu-Braze-Webhook erstellen und Allowlisting verwenden, sehen Sie sich die Liste der freizugebenden IPs an.
API-Authentifizierung und -Sicherheit
Bearer-Token-Authentifizierung
Braze authentifiziert REST-API-Anfragen mithilfe des REST-API-Schlüssels, der als Bearer-Token im Authorization-Anfrage-Header übergeben wird. Wenn Sie eine Anfrage senden, fügen Sie Ihren API-Schlüssel im folgenden Format ein:
Authorization: Bearer YOUR_REST_API_KEY
Bei jeder Anfrage führt Braze die folgenden serverseitigen Validierungsprüfungen durch:
- Token-Gültigkeit: Überprüft, ob der REST-API-Schlüssel in Braze existiert und aktiv ist (z. B. nicht widerrufen oder deaktiviert).
- Token-Autorisierung: Bestätigt, dass der API-Schlüssel über die erforderlichen Berechtigungen für den angeforderten Endpunkt verfügt.
Wenn die Authentifizierung fehlschlägt, gibt die API eine Fehlerantwort mit einem HTTP-Statuscode zurück. Zum Beispiel weist 401 Unauthorized auf einen ungültigen oder fehlenden Schlüssel hin, während 403 Forbidden bedeutet, dass der Schlüssel keine Berechtigung für den angeforderten Endpunkt hat. Weitere Informationen finden Sie unter API-Fehler.
Groß-/Kleinschreibung von Anfrage-Headern
HTTP-Headernamen sind nicht zwischen Groß- und Kleinschreibung unterscheidend, sodass Authorization und authorization gleichwertig sind. Dasselbe gilt für andere Standard-Anfrage-Header, wie z. B. Content-Type. Senden Sie die Schreibweise, die Ihr HTTP-Client erzeugt.
Braze akzeptiert auch jede Schreibweise des Bearer-Schemas (Bearer, bearer oder BEARER). Senden Sie den REST-API-Schlüssel selbst genau so, wie er ausgestellt wurde.
Sicherheit auf Netzwerkebene
REST-API-Anfragen an Braze werden durch Transport Layer Security (TLS)-Verschlüsselung über den gesamten Anfragepfad geschützt. Die folgende Tabelle beschreibt den Netzwerkfluss für eine API-Anfrage von Ihrem Server an Braze:
| Schritt | Komponente | Beschreibung |
|---|---|---|
| 1 | Ihr Server | Initiiert eine HTTPS-Anfrage mit TLS-Verschlüsselung. |
| 2 | Cloudflare | Beendet die Client-TLS-Verbindung und wendet Schutzmaßnahmen auf Netzwerkebene an. |
| 3 | Network Load Balancer (NLB) | Leitet Pakete an die Anwendungsinfrastruktur weiter. NLBs arbeiten auf Layer 4, d. h. es gibt kein Layer-7-Proxying. Pakete werden ohne HTTP-Level-Inspektion oder -Modifikation weitergeleitet. |
| 4 | NGINX-Ingress | Beendet die interne TLS-Verbindung und leitet die Anfrage weiter. |
| 5 | Unicorn (Anwendungsserver) | Verarbeitet die authentifizierte Anfrage. |
Die TLS-Verschlüsselung deckt jede Verbindung in der Kette ab. Ihr Server verbindet sich über TLS mit Cloudflare, und Cloudflare stellt über den NLB eine separate TLS-Verbindung zum NGINX-Ingress her, sodass Ihr API-Schlüssel und Ihre Anfragedaten während der Übertragung verschlüsselt bleiben.
Zusätzliche Ressourcen
Ruby-Client-Bibliothek
Wenn Sie Braze mit Ruby implementieren, können Sie die Ruby-Client-Bibliothek verwenden, um die Dauer Ihres Datenimports zu verkürzen. Eine Client-Bibliothek ist eine Sammlung von Code, der spezifisch für eine Programmiersprache ist – in diesem Fall Ruby – und die Nutzung einer API erleichtert.
Die Ruby-Client-Bibliothek unterstützt die User-Endpunkte.
Diese Client-Bibliothek befindet sich in der Betaphase. Um diese Bibliothek zu verbessern, senden Sie Feedback an [email protected].