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, die Sie in Ihren Braze Campaigns referenzieren können. |
| Cloud-Datenaufnahme | Verwalten Sie Ihre Data-Warehouse-Integrationen und -Synchronisationen. |
| E-Mail-Listen und -Adressen | Richten Sie die bidirektionale Synchronisierung zwischen Braze und Ihren E-Mail-Systemen ein und verwalten Sie sie. |
| Exportieren | Greifen Sie auf verschiedene Details Ihrer Campaigns, Canvases, KPIs und mehr zu und exportieren Sie sie. |
| Medienbibliothek | Verwalten Sie Assets innerhalb von Braze. |
| Nachrichten | Planen, versenden und verwalten Sie Ihre Campaigns und Canvases. |
| Präferenzzentrum | Bauen Sie Ihr Präferenzzentrum auf und aktualisieren Sie das Styling. |
| SCIM | Verwalten Sie Nutzeridentitäten in cloudbasierten Anwendungen und Diensten. |
| SMS | Verwalten Sie die Telefonnummern Ihrer Nutzer:innen in Ihren Abo-Gruppen. |
| Abo-Gruppen | Auflistung und Update der im Braze-Dashboard gespeicherten Abo-Gruppen (SMS und E-Mail). |
| Templates | Erstellen und aktualisieren Sie Templates für E-Mail-Messaging und Content Blocks. |
| Nutzerdaten | Identifizieren, tracken und verwalten Sie Ihre Nutzer:innen. |
API-Definitionen
Im Folgenden finden Sie eine Übersicht der Begriffe, die in der Dokumentation der Braze REST API vorkommen können.
Endpunkte
Braze verwaltet eine Reihe von verschiedenen Instanzen für unser Dashboard und die REST-Endpunkte. Sobald Ihr Konto eingerichtet ist, melden Sie sich unter einer der folgenden URLs an. Verwenden Sie den richtigen REST-Endpunkt, je nachdem, welcher Instanz Sie zugewiesen sind. Wenn Sie sich nicht sicher sind, öffnen Sie ein Support-Ticket oder verwenden Sie die folgende Tabelle, um die URL des Dashboards, das Sie verwenden, dem richtigen REST-Endpunkt zuzuordnen.
Um Ihren REST-Endpunkt in Braze zu finden:
- Melden Sie sich bei Braze an und navigieren Sie zu Settings > APIs and Identifiers > API Keys.
- Wählen Sie einen vorhandenen API-Schlüssel aus oder klicken Sie auf Create API Key, um einen neuen Schlüssel zu generieren.
- 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, benutzen Sie den REST-Endpunkt.
Verwenden Sie für die SDK-Integration 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 Standard-Rate-Limit von 250.000 Anfragen pro Stunde. Bestimmte Anfragetypen unterliegen jedoch eigenen Rate-Limits, um große Datenmengen innerhalb der Kundenbasis besser verarbeiten zu können. Einzelheiten finden Sie unter API-Rate-Limits.
Nutzer-IDs
- Externe Nutzer-ID: Die
external_iddient als eindeutiger Bezeichner für Nutzer:innen, für die Sie Daten übermitteln. Dieser Bezeichner sollte mit dem übereinstimmen, den Sie im Braze SDK festgelegt haben, um zu vermeiden, dass mehrere Profile für dieselbe Person erstellt werden. - Braze-Nutzer-ID: Die
braze_iddient als eindeutiger Bezeichner für Nutzer:innen, der von Braze festgelegt wird. Sie können diesen Bezeichner verwenden, um Nutzer:innen über die REST API zu löschen, zusätzlich zu external_ids.
Weitere Informationen finden Sie in den folgenden Artikeln zu 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 übermitteln, um den API-Aufruf zu authentifizieren und die aufrufende Anwendung bzw. den/die 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 mit App-Bezeichnern zusammen, um Daten zu tracken, abzurufen, zu senden, zu exportieren und zu analysieren, damit ein reibungsloser Ablauf gewährleistet ist.
Workspaces und API-Schlüssel gehen bei Braze Hand in Hand. Workspaces sind so konzipiert, dass sie Versionen derselben Anwendung für mehrere Plattformen enthalten. Viele Kund:innen nutzen Workspaces auch, um kostenlose und Premium-Versionen ihrer Anwendungen auf derselben Plattform unterzubringen. Wie Sie vielleicht bemerken, nutzen auch diese Workspaces die REST API und haben ihre eigenen REST-API-Schlüssel. Diese Schlüssel können individuell angepasst werden, um den Zugriff auf bestimmte Endpunkte der API zu ermöglichen. Jeder Aufruf der API muss einen Schlüssel mit Zugriff auf den entsprechenden Endpunkt enthalten.
Wir bezeichnen sowohl den REST-API-Schlüssel als auch den Workspace-API-Schlüssel als api_key. Der api_key ist in jeder Anfrage als Anfrage-Header enthalten und dient als Authentifizierungsschlüssel, der Ihnen die Nutzung unserer REST APIs erlaubt. Diese REST APIs dienen dem Tracking von Nutzer:innen, dem Versand von Nachrichten, dem Export von Nutzerdaten und vielem 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 bestimmte Berechtigungen zuweisen, können Sie genau festlegen, welche Aufrufe ein API-Schlüssel authentifizieren kann.
Neben den REST-API-Schlüsseln gibt es auch Bezeichner-Schlüssel, mit denen Sie bestimmte Elemente wie Apps, Templates, Canvases, Campaigns, Content Cards und Segmente über die API referenzieren können. Weitere Informationen finden Sie unter API-Bezeichnertypen.
REST-API-Schlüssel erstellen
So erstellen Sie einen neuen REST-API-Schlüssel:
- Gehen Sie zu Settings > APIs and Identifiers.
- Wählen Sie Create API Key.
- Geben Sie Ihrem neuen Schlüssel einen Namen, um ihn auf einen Blick identifizieren zu können.
- Geben Sie die zulässigen IP-Adressen und Subnetze für den neuen Schlüssel an.
- Wählen Sie aus, welche Berechtigungen mit Ihrem neuen Schlüssel verknüpft werden sollen.
Beachten Sie, dass Sie nach der Erstellung eines neuen API-Schlüssels den Umfang der Berechtigungen oder die zugelassenen IPs nicht mehr bearbeiten können. Diese Einschränkung besteht aus Sicherheitsgründen. Wenn Sie den Geltungsbereich eines Schlüssels ändern müssen, erstellen Sie einen neuen Schlüssel mit den aktualisierten Berechtigungen und implementieren Sie diesen anstelle des alten. Nachdem Sie Ihre Implementierung abgeschlossen haben, können Sie den alten Schlüssel löschen.
Berechtigungen für REST-API-Schlüssel
API-Schlüssel-Berechtigungen sind Berechtigungen, die Sie einem/einer Nutzer:in oder einer Gruppe zuweisen können, um deren Zugriff auf bestimmte API-Aufrufe zu beschränken. Um Ihre Liste der API-Schlüssel-Berechtigungen anzuzeigen, gehen Sie zu Settings > APIs and Identifiers und wählen Sie Ihren API-Schlüssel aus.
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
users.track |
/users/track |
Aufzeichnen von Nutzerattributen, angepassten Events und Käufen. |
users.delete |
/users/delete |
Löschen beliebiger Nutzer:innen. |
users.alias.new |
/users/alias/new |
Erstellen eines neuen Alias für bestehende Nutzer:innen. |
users.identify |
/users/identify |
Identifizieren eines Alias-only-Nutzers mit einer externen ID. |
users.export.ids |
/users/export/ids |
Abfragen von Nutzerprofil-Informationen nach Nutzer-ID. |
users.export.segment |
/users/export/segment |
Abfragen von Nutzerprofil-Informationen nach Segment. |
users.merge |
/users/merge |
Zusammenführen zweier bestehender Nutzer:innen. |
users.external_ids.rename |
/users/external_ids/rename |
Ändern der externen ID von bestehenden Nutzer:innen. |
users.external_ids.remove |
/users/external_ids/remove |
Entfernen der externen ID von bestehenden Nutzer:innen. |
users.alias.update |
/users/alias/update |
Aktualisieren eines Alias für bestehende Nutzer:innen. |
users.export.global_control_group |
/users/export/global_control_group |
Abfragen von Nutzerprofil-Informationen in der globalen Kontrollgruppe. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
email.unsubscribe |
/email/unsubscribes |
Abfragen von abgemeldeten E-Mail-Adressen. |
email.status |
/email/status |
Ändern des E-Mail-Adress-Status. |
email.hard_bounces |
/email/hard_bounces |
Abfragen von E-Mail-Adressen mit Hard Bounces. |
email.bounce.remove |
/email/bounce/remove |
Entfernen von E-Mail-Adressen aus Ihrer Hard-Bounce-Liste. |
email.spam.remove |
/email/spam/remove |
Entfernen von E-Mail-Adressen aus Ihrer Spam-Liste. |
email.blacklist |
/email/blacklist |
E-Mail-Adressen auf die Blockliste setzen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
campaigns.trigger.send |
/campaigns/trigger/send |
Triggern des Versands einer bestehenden Campaign. |
campaigns.trigger.schedule.create |
/campaigns/trigger/schedule/create |
Planen des Versands einer Campaign mit API-gesteuerter Zustellung. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Aktualisieren einer Campaign, die mit API-gesteuerter Zustellung geplant ist. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Löschen einer Campaign, die mit API-gesteuerter Zustellung geplant ist. |
campaigns.list |
/campaigns/list |
Abfragen einer Liste von Campaigns. |
campaigns.data_series |
/campaigns/data_series |
Abfragen von Campaign-Analytics über einen bestimmten Zeitraum. |
campaigns.details |
/campaigns/details |
Abfragen von Details zu einer bestimmten Campaign. |
sends.data_series |
/sends/data_series |
Abfragen von Analytics zum Nachrichtenversand über einen bestimmten Zeitraum. |
sends.id.create |
/sends/id/create |
Erstellen einer Sende-ID für das Tracking von Nachrichten-Blasts. |
campaigns.url_info.details |
/campaigns/url_info/details |
Abfragen der URL-Details zu einer bestimmten Nachrichtenvariante in einer Campaign. |
transactional.send |
/transactional/v1/campaigns/{campaign_id}/send |
Ermöglicht das Versenden von transaktionalen Nachrichten über den Endpunkt für transaktionale Nachrichten. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
canvas.trigger.send |
/canvas/trigger/send |
Triggern des Versands eines vorhandenen Canvas. |
canvas.trigger.schedule.create |
/canvas/trigger/schedule/create |
Planen des Versands eines Canvas mit API-gesteuerter Zustellung. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Aktualisieren eines Canvas mit API-gesteuerter Zustellung. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Löschen eines Canvas mit API-gesteuerter Zustellung. |
canvas.list |
/canvas/list |
Abfragen einer Liste von Canvases. |
canvas.data_series |
/canvas/data_series |
Abfragen von Canvas-Analytics über einen bestimmten Zeitraum. |
canvas.details |
/canvas/details |
Abfragen von Details zu einem bestimmten Canvas. |
canvas.data_summary |
/canvas/data_summary |
Abfragen von aggregierten Canvas-Analytics über einen bestimmten Zeitraum. |
canvas.url_info.details |
/canvas/url_info/details |
Abfragen der URL-Details zu einer bestimmten Nachrichtenvariante in einem Canvas-Schritt. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
segments.list |
/segments/list |
Abfragen einer Liste von Segmenten. |
segments.data_series |
/segments/data_series |
Abfragen von Segment-Analytics über einen bestimmten Zeitraum. |
segments.details |
/segments/details |
Abfragen von Details zu einem bestimmten Segment. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
purchases.product_list |
/purchases/product_list |
Abfragen einer Liste von Produkten, die in Ihrer App gekauft wurden. |
purchases.revenue_series |
/purchases/revenue_series |
Abfragen des Gesamtbetrags, der über einen bestimmten Zeitraum pro Tag in Ihrer App ausgegeben wurde. |
purchases.quantity_series |
/purchases/quantity_series |
Abfragen der Gesamtzahl der Käufe pro Tag in Ihrer App über einen bestimmten Zeitraum. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
events.list |
/events/list |
Abfragen einer Liste angepasster Events. |
events.data_series |
/events/data_series |
Abfragen von Vorkommen eines angepassten Events über einen bestimmten Zeitraum. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sessions.data_series |
/sessions/data_series |
Abfragen der Sitzungen pro Tag über einen bestimmten Zeitraum. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
kpi.dau.data_series |
/kpi/dau/data_series |
Abfragen von eindeutigen aktiven Nutzer:innen pro Tag über einen bestimmten Zeitraum. |
kpi.mau.data_series |
/kpi/mau/data_series |
Abfragen der Gesamtzahl eindeutiger aktiver Nutzer:innen über ein fortlaufendes Zeitfenster von 30 Tagen in einem bestimmten Zeitbereich. |
kpi.new_users.data_series |
/kpi/new_users/data_series |
Abfragen von neuen Nutzer:innen pro Tag über einen bestimmten Zeitraum. |
kpi.uninstalls.data_series |
/kpi/uninstalls/data_series |
Abfragen von App-Deinstallationen pro Tag über einen bestimmten Zeitraum. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
templates.email.create |
/templates/email/create |
Erstellen eines neuen E-Mail-Templates im Dashboard. |
templates.email.info |
/templates/email/info |
Abfragen von Informationen zu einem bestimmten Template. |
templates.email.list |
/templates/email/list |
Abfragen einer Liste der E-Mail-Templates. |
templates.email.update |
/templates/email/update |
Aktualisieren eines im Dashboard gespeicherten E-Mail-Templates. |
| Berechtigung | Beschreibung |
|---|---|
sso.saml.login |
Richten Sie die vom Identitätsanbieter initiierte Anmeldung ein. Weitere Informationen finden Sie unter Anmeldung durch den Service Provider (SP). |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
content_blocks.info |
/content_blocks/info |
Abfragen von Informationen zu einem bestimmten Template. |
content_blocks.list |
/content_blocks/list |
Abfragen einer Liste der Content Blocks. |
content_blocks.create |
/content_blocks/create |
Erstellen eines neuen Content-Blocks im Dashboard. |
content_blocks.update |
/content_blocks_update |
Aktualisieren eines bestehenden Content-Blocks im Dashboard. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
preference_center.get |
/preference_center/v1/{preferenceCenterExternalId} |
Abrufen eines Präferenzzentrums. |
preference_center.list |
/preference_center/v1/list |
Auflisten von Präferenzzentren. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Erstellen oder Aktualisieren eines Präferenzzentrums. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Abrufen eines Links zum Präferenzzentrum für eine:n Nutzer:in. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
subscription.status.set |
/subscription/status/set |
Abo-Gruppenstatus festlegen. |
subscription.status.get |
/subscription/status/get |
Abrufen des Abo-Gruppenstatus. |
subscription.groups.get |
/subscription/user/status |
Abrufen des Status von Abo-Gruppen, bei denen bestimmte Nutzer:innen explizit angemeldet oder abgemeldet sind. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sms.invalid_phone_numbers |
/sms/invalid_phone_numbers |
Abfragen von ungültigen Telefonnummern. |
sms.invalid_phone_numbers.remove |
/sms/invalid_phone_numbers/remove |
Entfernen der Kennzeichnung für ungültige Telefonnummern von Nutzer:innen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
catalogs.add_items |
/catalogs/{catalog_name}/items |
Hinzufügen mehrerer Artikel zu einem bestehenden Katalog. |
catalogs.update_items |
/catalogs/{catalog_name}/items |
Aktualisieren mehrerer Artikel in einem bestehenden Katalog. |
catalogs.delete_items |
/catalogs/{catalog_name}/items |
Löschen mehrerer Artikel aus einem bestehenden Katalog. |
catalogs.get_item |
/catalogs/{catalog_name}/items/{item_id} |
Abrufen eines einzelnen Artikels aus einem bestehenden Katalog. |
catalogs.update_item |
/catalogs/{catalog_name}/items/{item_id} |
Aktualisieren eines einzelnen Artikels in einem bestehenden Katalog. |
catalogs.create_item |
/catalogs/{catalog_name}/items/{item_id} |
Erstellen eines einzelnen Artikels in einem bestehenden Katalog. |
catalogs.delete_item |
/catalogs/{catalog_name}/items/{item_id} |
Löschen eines einzelnen Artikels aus einem bestehenden Katalog. |
catalogs.replace_item |
/catalogs/{catalog_name}/items/{item_id} |
Ersetzen eines einzelnen Artikels in einem bestehenden Katalog. |
catalogs.create |
/catalogs |
Erstellen eines Katalogs. |
catalogs.get |
/catalogs |
Abrufen einer Liste von Katalogen. |
catalogs.delete |
/catalogs/{catalog_name} |
Löschen eines Katalogs. |
catalogs.get_items |
/catalogs/{catalog_name}/items |
Abrufen von Artikelvorschauen aus einem bestehenden Katalog. |
catalogs.replace_items |
/catalogs/{catalog_name}/items |
Ersetzen von Artikeln in einem bestehenden Katalog. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sdk_authentication.create |
/app_group/sdk_authentication/create |
Erstellen eines neuen SDK-Authentifizierungsschlüssels für Ihre App. |
sdk_authentication.primary |
/app_group/sdk_authentication/primary |
Markieren eines SDK-Authentifizierungsschlüssels als Primärschlüssel für Ihre App. |
sdk_authentication.delete |
/app_group/sdk_authentication/delete |
Löschen eines SDK-Authentifizierungsschlüssels für Ihre App. |
sdk_authentication.keys |
/app_group/sdk_authentication/keys |
Abrufen aller SDK-Authentifizierungsschlüssel für Ihre App. |
REST-API-Schlüssel verwalten
Unter Settings > APIs and Identifiers > Tab API Keys können Sie Details zu vorhandenen REST-API-Schlüsseln einsehen oder diese löschen. 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 Key Name | Der Name, der dem Schlüssel bei der Erstellung gegeben wurde. |
| Identifier | Der API-Schlüssel. |
| Created By | Die E-Mail-Adresse des/der Nutzer:in, der/die den Schlüssel erstellt hat. Dieses Feld wird für Schlüssel, die vor Juni 2023 erstellt wurden, als „N/A“ angezeigt. |
| Date Created | Das Datum, an dem dieser Schlüssel erstellt wurde. |
| Last Seen | Das Datum, an dem dieser Schlüssel zuletzt verwendet wurde. Dieses Feld wird für Schlüssel, die noch nie verwendet wurden, als „N/A“ angezeigt. |
Um die Details eines API-Schlüssels anzuzeigen, bewegen Sie den Mauszeiger über den Schlüssel und wählen Sie View. Hier sehen Sie alle Berechtigungen dieses Schlüssels, die IPs auf der Whitelist (falls vorhanden) und ob dieser Schlüssel in die IP-Whitelist von Braze aufgenommen wurde.
Beachten Sie, dass Braze beim Löschen eines/einer Nutzer:in die zugehörigen API-Schlüssel, die diese Person erstellt hat, nicht löscht. Um einen Schlüssel zu löschen, bewegen Sie den Mauszeiger über den Schlüssel und wählen Sie Delete.
Sicherheit von REST-API-Schlüsseln
API-Schlüssel werden zur Authentifizierung eines API-Aufrufs verwendet. Wenn Sie einen neuen REST-API-Schlüssel erstellen, müssen Sie ihm Zugriff auf bestimmte Endpunkte geben. Indem Sie einem API-Schlüssel bestimmte Berechtigungen zuweisen, können Sie genau festlegen, welche Aufrufe ein API-Schlüssel authentifizieren kann.
Da REST-API-Schlüssel den Zugang zu potenziell sensiblen REST-API-Endpunkten erlauben, sollten Sie diese Schlüssel sichern und nur mit vertrauenswürdigen Partnern teilen. Sie sollten niemals öffentlich zugänglich gemacht werden. Verwenden Sie diesen Schlüssel beispielsweise nicht, um AJAX-Aufrufe von Ihrer Website aus zu tätigen, und geben Sie ihn auch nicht auf andere Weise öffentlich preis.
Eine gute Sicherheitspraxis besteht darin, einem/einer Nutzer:in nur so viel Zugriff zu gewähren, wie für die Erfüllung der Aufgabe benötigt wird. Dieses Prinzip kann auch auf API-Schlüssel angewendet werden, indem jedem Schlüssel Berechtigungen zugewiesen werden. Diese Berechtigungen bieten Ihnen mehr Sicherheit und Kontrolle über die verschiedenen Bereiche Ihres Kontos.
Da REST-API-Schlüssel den Zugang zu potenziell sensiblen REST-API-Endpunkten erlauben, sollten Sie sicherstellen, dass sie sicher gespeichert und verwendet werden. Verwenden Sie diesen Schlüssel beispielsweise nicht, um AJAX-Aufrufe von Ihrer Website aus zu tätigen, und geben Sie ihn auch nicht auf andere Weise öffentlich preis.
Sollten Sie versehentlich einen Schlüssel preisgeben, können Sie ihn über die Entwicklungskonsole löschen. Wenn Sie Hilfe bei diesem Vorgang benötigen, ö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.
| 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 preisgeben. | Für die öffentliche Nutzung konzipiert. Wird in Ihrem App-Binary gebündelt oder ist im JavaScript des Webbrowsers sichtbar, ähnlich einer Google-Analytics-Tracking-ID. |
| Lösung bei Preisgabe | Widerrufen Sie den Schlüssel sofort und erstellen Sie einen Ersatz unter Settings > APIs and Identifiers > API Keys. Ein preisgegebener REST-API-Schlüssel kann zum Senden von Nachrichten, Exportieren von Nutzerdaten oder Ändern von Kontoeinstellungen verwendet werden. | Keine Maßnahme erforderlich. Ein SDK-API-Schlüssel kann nur Daten aufnehmen und clientseitiges Messaging abrufen (wie In-App-Nachrichten und Content Cards). Er kann keine Nutzerdaten exportieren, keine Nachrichten in Ihrem Namen senden oder Campaigns ändern. |
API-IP-Allowlisting
Für zusätzliche Sicherheit können Sie eine Liste von IP-Adressen und Subnetzen angeben, die für einen bestimmten REST-API-Schlüssel Anfragen an die REST API stellen dürfen. Dies wird als Allowlisting oder Whitelisting bezeichnet. Um bestimmte IP-Adressen oder Subnetze zuzulassen, fügen Sie sie bei der Erstellung eines neuen REST-API-Schlüssels dem Abschnitt Whitelist IPs hinzu:
Wenn Sie nichts angeben, können Anfragen von jeder IP-Adresse gesendet werden.
Wenn Sie einen Braze-to-Braze-Webhook erstellen und Allowlisting verwenden, finden Sie hier die Liste der IP-Adressen, die auf die Whitelist gesetzt werden müssen.
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 übermittelt wird. Wenn Sie eine Anfrage senden, geben Sie Ihren API-Schlüssel im folgenden Format an:
1
Authorization: Bearer YOUR_REST_API_KEY
Bei jeder Anfrage führt Braze die folgenden serverseitigen Validierungsprüfungen durch:
- Gültigkeit des Tokens: Überprüft, ob der REST-API-Schlüssel in Braze vorhanden und aktiv ist (d. h. nicht widerrufen oder deaktiviert wurde).
- Token-Autorisierung: Bestätigt, dass der API-Schlüssel über die erforderlichen Berechtigungen für den angeforderten Endpunkt verfügt.
Sollte die Authentifizierung fehlschlagen, gibt die API eine Fehlerantwort mit einem HTTP-Statuscode zurück. Beispielsweise weist 401 Unauthorized auf einen ungültigen oder fehlenden Schlüssel hin, während 403 Forbidden angibt, dass der Schlüssel keine Berechtigung für den angeforderten Endpunkt hat. Weitere Informationen finden Sie unter API-Fehler.
Sicherheit auf Netzwerkebene
REST-API-Anfragen an Braze werden über den gesamten Anfragepfad hinweg durch TLS-Verschlüsselung (Transport Layer Security) 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 TLS-Verbindung des Clients und wendet Schutzmaßnahmen auf Netzwerkebene an. |
| 3 | Netzwerk-Lastenausgleich (NLB) | Leitet Pakete an die Anwendungsinfrastruktur weiter. NLBs arbeiten auf Layer 4, d. h. es findet kein Layer-7-Proxying statt. Pakete werden ohne Überprüfung oder Änderung auf HTTP-Ebene 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 umfasst jede Verbindung in der Kette. Ihr Server stellt über TLS eine Verbindung zu Cloudflare her, und Cloudflare baut über den NLB eine separate TLS-Verbindung zum NGINX-Ingress auf, 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 Zeit für den Datenimport zu verkürzen. Eine Client-Bibliothek ist eine Sammlung von Code für eine bestimmte Programmiersprache – in diesem Fall Ruby –, die die Verwendung einer API erleichtert.
Die Ruby-Client-Bibliothek unterstützt die Nutzer-Endpunkte.
Diese Client-Bibliothek befindet sich in der Beta-Phase. Um zur Verbesserung dieser Bibliothek beizutragen, senden Sie Ihr Feedback an [email protected].