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 |
|---|---|
| Catalogs | Erstellen und verwalten Sie Kataloge und Katalogartikel, auf die Sie in Ihren Braze-Campaigns verweisen 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äferenzzentrum | Erstellen Sie Ihr Präferenzzentrum und aktualisieren Sie dessen Darstellung. |
| SCIM | Verwalten Sie Nutzer:innenidentitäten in cloudbasierten Anwendungen und Diensten. |
| SMS | Verwalten Sie die Telefonnummern Ihrer Nutzer:innen in Ihren Abo-Gruppen. |
| Abo-Gruppen | Listen Sie SMS- und E-Mail-Abo-Gruppen auf, die im Braze-Dashboard gespeichert sind, und aktualisieren Sie diese. |
| 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 der Begriffe, die Ihnen in der Braze REST API-Dokumentation begegnen können.
Endpunkte
Braze verwaltet eine Reihe verschiedener Instanzen für unser Dashboard und unsere REST-Endpunkte. Wenn Ihr Konto eingerichtet wird, melden Sie sich bei einer der folgenden URLs an. Verwenden Sie den richtigen REST-Endpunkt basierend auf der Instanz, der Sie zugewiesen sind. Falls Sie sich nicht sicher sind, eröffnen Sie ein Support-Ticket oder nutzen Sie die folgende Tabelle, um die URL des von Ihnen verwendeten 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 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 hat 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 festlegen, 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 Internet.
Ü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 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-Identifier-Schlüsseln, um Daten zu verfolgen, abzurufen, zu senden, zu exportieren und zu analysieren und so sicherzustellen, dass alles reibungslos funktioniert.
Workspaces und API-Schlüssel gehören bei Braze zusammen. 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 zu verwalten. 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 konfiguriert werden, um Zugriff auf bestimmte Endpunkte der API zu gewähren. 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 ist in jeder Anfrage als Anfrage-Header enthalten 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. 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 einen Schlüsseltyp namens Identifier-Schlüssel, der verwendet werden kann, um bestimmte Elemente wie Apps, Templates, Canvases, Campaigns, Content Cards und Segmente ü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:
- Navigieren 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 erlaubte IP-Adressen und Subnetze für den neuen Schlüssel an.
- Wählen Sie die Berechtigungen aus, die mit Ihrem neuen Schlüssel verknüpft werden sollen.
Beachten Sie, dass Sie nach der Erstellung eines neuen API-Schlüssels weder den Berechtigungsumfang noch die erlaubten IPs 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. 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 Rechte, die Sie einer Nutzer:in oder Gruppe zuweisen können, um deren Zugriff auf bestimmte API-Aufrufe einzuschränken. Um Ihre Liste der API-Schlüssel-Berechtigungen einzusehen, navigieren 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.delete |
/users/delete |
Beliebige Nutzer:innen 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 Alias-only-Nutzer:in mit einer externen ID identifizieren. |
users.export.ids |
/users/export/ids |
Nutzerprofilinformationen anhand der Nutzer-ID abfragen. |
users.export.segment |
/users/export/segment |
Nutzerprofilinformationen anhand eines Segments abfragen. |
users.merge |
/users/merge |
Zwei bestehende Nutzer:innen zusammenführen. |
users.external_ids.rename |
/users/external_ids/rename |
Die externe ID einer/eines bestehenden Nutzer:in ändern. |
users.external_ids.remove |
/users/external_ids/remove |
Die externe ID einer/eines 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-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 Blocklist 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 zu einem 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 |
Einen Versand einer Campaign mit API-ausgelöster Zustellung planen. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Eine Campaign mit API-ausgelöster Zustellung aktualisieren. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Eine Campaign mit API-ausgelöster 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 Send-ID für das Tracking von Massenversand erstellen. |
campaigns.url_info.details |
/campaigns/url_info/details |
URL-Details einer bestimmten Nachrichtenvariante innerhalb einer Campaign abfragen. |
transactional.send |
/transactional/v1/campaigns/{campaign_id}/send |
Ermöglicht den Versand transaktionaler Nachrichten über den Endpunkt für transaktionales Messaging. |
| 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-ausgelöster Zustellung planen. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Einen Canvas mit API-ausgelöster Zustellung aktualisieren. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Einen Canvas mit API-ausgelöster 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. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
segments.list |
/segments/list |
Eine Liste von Segmenten 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 |
Die gesamten täglichen Ausgaben in Ihrer App über einen Zeitraum abfragen. |
purchases.quantity_series |
/purchases/quantity_series |
Die Gesamtanzahl der täglichen Käufe 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 der eindeutigen aktiven 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 |
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 Einstellungscenter abrufen. |
preference_center.list |
/preference_center/v1/list |
Einstellungscenter auflisten. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Ein Einstellungscenter erstellen oder aktualisieren. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Einen Link zum Einstellungscenter 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 der 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 für ungültige Telefonnummern von 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 |
Vorschau der Artikel eines bestehenden Katalogs 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 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 bestehender REST-API-Schlüssel einsehen oder sie löschen, indem Sie zu Einstellungen > APIs und Bezeichner > Tab API-Schlüssel navigieren. Beachten Sie, dass Sie REST-API-Schlüssel nach der Erstellung nicht mehr bearbeiten können.
Der Tab API-Schlüssel enthält die folgenden Informationen für jeden Schlüssel:
| Feld | Beschreibung |
|---|---|
| API-Schlüssel-Name | Der Name, der dem Schlüssel bei der Erstellung gegeben wurde. |
| Bezeichner | Der API-Schlüssel. |
| Erstellt von | Die E-Mail-Adresse der Nutzer:in, 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 einzusehen, fahren Sie mit der Maus über den Schlüssel und wählen Sie Anzeigen. Dies umfasst alle Berechtigungen dieses Schlüssels, die erlaubten IPs (falls vorhanden) und ob dieser Schlüssel für das Braze-IP-Whitelisting aktiviert ist.
Beachten Sie, dass beim Löschen einer Nutzer:in Braze die zugehörigen API-Schlüssel, die diese 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 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. 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 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 auf andere Weise öffentlich bereit.
Eine gute Sicherheitspraxis ist es, Nutzer:innen nur so viel Zugriff zu gewähren, wie für ihre Arbeit notwendig ist: Dieses Prinzip kann auch auf API-Schlüssel angewendet 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 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 auf andere Weise öffentlich bereit.
Wenn Sie versehentlich einen Schlüssel offenlegen, können Sie ihn in der Entwicklungskonsole löschen. Für Hilfe bei diesem Vorgang erstellen 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 Identifizierung für das Braze SDK (Datenaufnahme, In-App-Nachrichten, Content Cards) |
| Sichtbarkeit | Muss privat bleiben. Niemals in clientseitigem Code, öffentlichen Repositories oder Nutzeranwendungen offenlegen. | Für die öffentliche Nutzung konzipiert. Im App-Binary gebündelt oder im Webbrowser-JavaScript sichtbar, ähnlich einer Google-Analytics-Tracking-ID. |
| Lösung bei Offenlegung | Den Schlüssel sofort widerrufen und einen Ersatz unter Einstellungen > APIs und Bezeichner > API-Schlüssel erstellen. Ein offengelegter 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 clientseitige Nachrichten abrufen (wie In-App-Nachrichten und Content Cards). Er kann keine Nutzerdaten exportieren, 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 festlegen, 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 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 Allowlisting verwenden, sehen Sie sich die Liste der IPs zum Whitelisten 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, 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:
- Token-Gültigkeit: Überprüft, ob der REST-API-Schlüssel in Braze existiert und aktiv ist (zum Beispiel 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 zeigt 401 Unauthorized einen ungültigen oder fehlenden Schlüssel an, während 403 Forbidden darauf hinweist, 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-Header-Namen sind nicht zwischen Groß- und Kleinschreibung unterscheidend, daher sind Authorization und authorization gleichwertig. Das Gleiche 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 | 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, das heißt, es findet kein Layer-7-Proxying statt. Pakete werden ohne HTTP-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 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, der auf eine bestimmte Programmiersprache zugeschnitten ist – in diesem Fall Ruby – und die Nutzung einer API erleichtert.
Die Ruby-Client-Bibliothek unterstützt die Nutzer:innen-Endpunkte.
Diese Client-Bibliothek befindet sich in der Betaphase. Um diese Bibliothek zu verbessern, senden Sie Ihr Feedback an [email protected].