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 -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. |
| Präferenzcenter | Erstellen Sie Ihr Präferenzcenter und aktualisieren Sie dessen Gestaltung. |
| SCIM | Verwalten Sie Nutzer:innen-Identitä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, tracken 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 verwaltet verschiedene 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, für die Sie bereitgestellt wurden. Wenn Sie unsicher sind, eröffnen Sie ein Support-Ticket oder verwenden Sie die folgende Tabelle, um die URL des Dashboards, das Sie nutzen, 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 anzulegen.
- 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 gilt bei Braze ein Standard-Rate-Limit von 250.000 Anfragen pro Stunde. Bestimmte Anfragetypen haben jedoch eigene Rate-Limits, um große Datenmengen über den gesamten Kundenstamm 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 basierend auf Ihrer Plattform: iOS, Android und Web.
Über REST-API-Schlüssel
Ein REST Application Programming Interface-Schlüssel (REST-API-Schlüssel) 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 sichergestellt ist, dass alles reibungslos läuft.
Workspaces und API-Schlüssel gehen bei Braze Hand in Hand. Workspaces sind dafür konzipiert, Versionen derselben Anwendung über mehrere Plattformen hinweg zu beherbergen. Viele Kund:innen nutzen Workspaces auch, um kostenlose und Premium-Versionen ihrer Anwendungen auf derselben Plattform zu verwalten. Wie Ihnen vielleicht auffällt, nutzen diese Workspaces ebenfalls die REST API und verfügen über eigene REST-API-Schlüssel. Diese Schlüssel können individuell so eingeschränkt werden, dass sie nur Zugriff auf bestimmte Endpunkte der API bieten. Jeder API-Aufruf muss einen Schlüssel mit Zugriff auf den aufgerufenen Endpunkt enthalten.
Wir bezeichnen sowohl den REST-API-Schlüssel als auch den Workspace-API-Schlüssel als api_key. Der api_key wird in 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 verfolgen, Nachrichten zu senden, Nutzerdaten zu exportieren und vieles mehr. Wenn Sie einen neuen REST-API-Schlüssel erstellen, müssen Sie ihm Zugriff auf bestimmte Endpunkte gewähren. Durch die Zuweisung spezifischer Berechtigungen an einen API-Schlüssel 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 über die API auf bestimmte Objekte wie Apps, Templates, Canvases, Campaigns, Content Cards und Segments zu verweisen. 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 Identifizierung.
- Geben Sie zugelassene IP-Adressen und Subnetze für den neuen Schlüssel an.
- Wählen Sie die Berechtigungen, die mit Ihrem neuen Schlüssel verknüpft sein sollen.
Beachten Sie, dass Sie nach der Erstellung eines neuen API-Schlüssels den Berechtigungsumfang oder die zugelassenen 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 Schlüssel anstelle des alten. Nach Abschluss Ihrer Implementierung können Sie den alten Schlüssel löschen.
REST-API-Schlüssel-Berechtigungen
API-Schlüssel-Berechtigungen sind Berechtigungen, die Sie einem Nutzer:in oder einer Gruppe zuweisen können, um deren Zugriff auf bestimmte API-Aufrufe einzuschränken. Um Ihre Liste der API-Schlüssel-Berechtigungen 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 |
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 per Alias existierende:n 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 |
Externe ID eines:einer bestehenden Nutzer:in ändern. |
users.external_ids.remove |
/users/external_ids/remove |
Externe ID eines:einer bestehenden 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 Bounces von E-Mail-Adressen abfragen. |
email.bounce.remove |
/email/bounce/remove |
E-Mail-Adressen aus Ihrer Hard-Bounce-Liste entfernen. |
email.spam.remove |
/email/spam/remove |
E-Mail-Adressen aus Ihrer Spam-Liste entfernen. |
email.blacklist |
/email/blacklist |
E-Mail-Adressen auf die Sperrliste setzen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
messages.send |
/messages/send |
Eine sofortige Nachricht an bestimmte Nutzer:innen senden. |
messages.schedule.create |
/messages/schedule/create |
Den Versand einer Nachricht für einen bestimmten Zeitpunkt planen. |
messages.schedule.update |
/messages/schedule/update |
Eine geplante Nachricht aktualisieren. |
messages.schedule.delete |
/messages/schedule/delete |
Eine geplante Nachricht löschen. |
messages.schedule_broadcasts |
/messages/scheduled_broadcasts |
Alle geplanten Broadcast-Nachrichten abfragen. |
messages.live_activity.update |
/messages/live_activity/update |
Eine iOS Live Activity aktualisieren. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
campaigns.trigger.send |
/campaigns/trigger/send |
Den Versand einer bestehenden Campaign auslösen. |
campaigns.trigger.schedule.create |
/campaigns/trigger/schedule/create |
Den Versand einer Campaign mit API-getriggerter Zustellung planen. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Eine Campaign mit API-getriggerter Zustellung aktualisieren. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Eine Campaign mit API-getriggerter 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 |
Versand-Analytics über einen Zeitraum abfragen. |
sends.id.create |
/sends/id/create |
Versand-ID für das Tracking von Massen-Nachrichten 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 mit aktiviertem Link Aliasing verfügbar. 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 das Senden von Transaktionsnachrichten über den Transactional-Messaging-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 |
Den Versand eines Canvas mit API-getriggerter Zustellung planen. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Einen Canvas mit API-getriggerter Zustellung aktualisieren. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Einen Canvas mit API-getriggerter 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 mit aktiviertem Link Aliasing verfügbar. 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 rollendes 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 |
Vom Identitätsanbieter initiierte Anmeldung einrichten. Weitere Informationen finden Sie unter Vom 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 Preference Center abrufen. |
preference_center.list |
/preference_center/v1/list |
Preference Center auflisten. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Ein Preference Center erstellen oder aktualisieren. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Einen Preference-Center-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 ungültiger Telefonnummern bei 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 Vorschau der Artikel 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ärschlüssel für Ihre App markieren. |
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 zu bestehenden REST-API-Schlüsseln anzeigen oder diese löschen unter Einstellungen > APIs und Bezeichner > Tab API Keys. Beachten Sie, dass REST-API-Schlüssel nach der Erstellung nicht mehr bearbeitet werden 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, fahren Sie mit der Maus über den Schlüssel und wählen Sie Anzeigen. Dies umfasst alle Berechtigungen dieses Schlüssels, zugelassene IPs (falls vorhanden) und ob dieser Schlüssel für das Braze IP-Whitelisting aktiviert ist.
Beachten Sie, dass beim Löschen eines:einer 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, fahren Sie mit der Maus über den Schlüssel und wählen Sie Löschen.
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 gewähren. Durch die Zuweisung spezifischer Berechtigungen an einen API-Schlüssel können Sie genau einschränken, welche Aufrufe ein API-Schlüssel authentifizieren kann.
Da REST-API-Schlüssel Zugang zu potenziell sensiblen REST-API-Endpunkten gewähren, sichern Sie diese Schlüssel ab und teilen Sie sie nur mit vertrauenswürdigen Partnern. Sie sollten niemals öffentlich zugänglich sein. Verwenden Sie diesen Schlüssel beispielsweise nicht für AJAX-Aufrufe von Ihrer Website aus und machen Sie ihn auch nicht anderweitig öffentlich zugänglich.
Eine gute Sicherheitspraxis besteht darin, Nutzer:innen nur so viel Zugriff zu geben, wie für die Erledigung ihrer Aufgabe nötig ist: Dieses Prinzip kann auch auf API-Schlüssel angewandt werden, indem Sie jedem Schlüssel Berechtigungen zuweisen. Diese Berechtigungen bieten Ihnen bessere Sicherheit und Kontrolle über die verschiedenen Bereiche Ihres Kontos.
Da REST-API-Schlüssel Zugang zu potenziell sensiblen REST-API-Endpunkten gewähren, stellen Sie sicher, dass sie sicher gespeichert und verwendet werden. Verwenden Sie diesen Schlüssel beispielsweise nicht für AJAX-Aufrufe von Ihrer Website aus und machen Sie ihn auch nicht anderweitig öffentlich zugänglich.
Wenn Sie versehentlich einen Schlüssel preisgeben, können Sie ihn über die 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 preisgeben. | Für die Öffentlichkeit bestimmt. Wird in Ihre App-Binary gebündelt oder ist im JavaScript des Webbrowsers sichtbar, ähnlich wie eine Google-Analytics-Tracking-ID. |
| Maßnahme bei Preisgabe | Widerrufen Sie den Schlüssel sofort und erstellen Sie einen Ersatz unter Einstellungen > APIs und Bezeichner > 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-Zulassungsliste
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 Zulassungsliste oder Whitelisting bezeichnet. Um bestimmte IP-Adressen oder Subnetze zuzulassen, fügen Sie diese 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 eine Zulassungsliste verwenden, sehen Sie sich die Liste der IPs zum Whitelisting 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. Beispielsweise weist 401 Unauthorized auf einen ungültigen oder fehlenden Schlüssel hin, während 403 Forbidden bedeutet, dass der Schlüssel nicht über die Berechtigung für den angeforderten Endpunkt verfügt. Weitere Informationen finden Sie unter API-Fehler.
Groß-/Kleinschreibung im Anfrage-Header
HTTP-Header-Namen sind nicht zwischen Groß- und Kleinschreibung unterscheidend, sodass Authorization und authorization gleichwertig sind. Dasselbe gilt für andere Standard-Anfrage-Header wie Content-Type. Senden Sie die Schreibweise, die Ihr HTTP-Client erzeugt.
Braze akzeptiert außerdem 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 | Terminiert 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 findet kein Layer-7-Proxying statt. Pakete werden ohne HTTP-Inspektion oder -Änderung weitergeleitet. |
| 4 | NGINX Ingress | Terminiert die interne TLS-Verbindung und leitet die Anfrage weiter. |
| 5 | Unicorn (Anwendungsserver) | Verarbeitet die authentifizierte Anfrage. |
Die TLS-Verschlüsselung deckt jedes Glied in der Kette ab. Ihr Server verbindet sich über TLS mit Cloudflare, und Cloudflare stellt eine separate TLS-Verbindung über den NLB 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, die speziell für eine Programmiersprache erstellt wurde – 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 Beta-Phase. Um diese Bibliothek zu verbessern, senden Sie Feedback an [email protected].