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 Verwendung 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 innerhalb von Braze. |
| Nachrichten | Planen, versenden und verwalten Sie Ihre Campaigns und Canvases. |
| Präferenzcenter | Erstellen Sie Ihr Präferenzcenter und aktualisieren Sie dessen Gestaltung. |
| 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 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 einen Überblick über Begriffe, die Ihnen in der Braze REST API-Dokumentation begegnen können.
Endpunkte
Braze betreibt 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 korrekten REST-Endpunkt basierend auf der Instanz, der Sie zugewiesen sind. Falls Sie sich unsicher sind, eröffnen Sie ein Support-Ticket oder nutzen Sie die folgende Tabelle, um die URL des Dashboards, das Sie verwenden, 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 Kundenstamm hinweg besser zu verarbeiten. 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 mit dem übereinstimmen, 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, 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 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-Identifikationsschlüsseln, um Daten zu verfolgen, darauf zuzugreifen, sie zu senden, zu exportieren und zu analysieren, damit 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 beherbergen. 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 haben ihre eigenen REST-API-Schlüssel. Diese Schlüssel können individuell so eingeschränkt werden, dass sie nur Zugriff auf bestimmte Endpunkte der API gewähren. Jeder Aufruf der API muss einen Schlüssel enthalten, der Zugriff auf den angesprochenen Endpunkt hat.
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 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 Identifikationsschlüssel, die verwendet werden können, 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:
- 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 zulässige 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 Berechtigungsumfang oder die zulässigen 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. Nachdem Sie Ihre Implementierung abgeschlossen haben, können Sie den alten Schlüssel löschen.
REST-API-Schlüssel-Berechtigungen
API-Schlüssel-Berechtigungen sind Berechtigungen, die Sie Nutzer:innen 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.delete |
/users/delete |
Beliebige Nutzer:innen löschen. |
users.alias.new |
/users/alias/new |
Einen neuen Alias für bestehende Nutzer:innen erstellen. |
users.identify |
/users/identify |
Alias-only-Nutzer:innen 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 bestehender Nutzer:innen ändern. |
users.external_ids.remove |
/users/external_ids/remove |
Die externe ID bestehender Nutzer:innen entfernen. |
users.alias.update |
/users/alias/update |
Einen Alias bestehender Nutzer:innen 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 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 Blockliste 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 |
Den Versand einer Campaign mit API-ausgelöster Zustellung planen. |
campaigns.trigger.schedule.update |
/campaigns/trigger/schedule/update |
Eine mit API-ausgelöster Zustellung geplante Campaign aktualisieren. |
campaigns.trigger.schedule.delete |
/campaigns/trigger/schedule/delete |
Eine mit API-ausgelöster Zustellung geplante Campaign 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 |
Nachrichten-Versand-Analytics über einen Zeitraum abfragen. |
sends.id.create |
/sends/id/create |
Versand-ID für das Tracking von Nachrichtenblasts 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. Falls 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 transaktionalen Nachrichten ü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-ausgelöster Zustellung planen. |
canvas.trigger.schedule.update |
/canvas/trigger/schedule/update |
Einen mit API-ausgelöster Zustellung geplanten Canvas aktualisieren. |
canvas.trigger.schedule.delete |
/canvas/trigger/schedule/delete |
Einen mit API-ausgelöster Zustellung geplanten Canvas 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 von 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. Falls 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 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 täglichen Gesamtausgaben 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 |
Gesamtanzahl 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 |
Vom Identitätsanbieter initiierte Anmeldung einrichten. Weitere Informationen finden Sie unter Service-Provider-initiierte Anmeldung (SP). |
| 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äferenzzentrum abrufen. |
preference_center.list |
/preference_center/v1/list |
Präferenzzentren auflisten. |
preference_center.update |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalID} |
Ein Präferenzzentrum erstellen oder aktualisieren. |
preference_center.user.get |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId} |
Einen Link zum Präferenzzentrum 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 und 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 Kennzeichnung ungültiger 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 |
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 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 anzeigen 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 |
|---|---|
| Name des API-Schlüssels | Der Name, der dem Schlüssel bei der Erstellung gegeben wurde. |
| Bezeichner | Der API-Schlüssel. |
| Erstellt von | Die E-Mail-Adresse der Person, 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 das Braze-IP-Whitelisting aktiviert ist.
Beachten Sie, dass beim Löschen von Nutzer:innen Braze 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 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, um AJAX-Aufrufe von Ihrer Website aus zu tätigen, oder machen Sie ihn auf andere Weise öffentlich zugänglich.
Eine gute Sicherheitspraxis ist es, Nutzer:innen nur so viel Zugriff zu gewähren, wie für die Erledigung ihrer Aufgaben erforderlich ist. Dieses Prinzip kann auch auf API-Schlüssel angewendet werden, indem Sie jedem Schlüssel Berechtigungen zuweisen. Diese Berechtigungen bieten Ihnen mehr 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, um AJAX-Aufrufe von Ihrer Website aus zu tätigen, oder machen Sie ihn auf andere Weise öffentlich zugänglich.
Wenn Sie versehentlich einen Schlüssel offenlegen, können Sie ihn in der Entwicklungskonsole löschen. Um Hilfe bei diesem Vorgang zu erhalten, ö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 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. | Dafür konzipiert, öffentlich zu sein. Im App-Binary gebündelt oder im Webbrowser-JavaScript sichtbar, ähnlich wie eine Google-Analytics-Tracking-ID. |
| Lösung bei Offenlegung | 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 clientseitiges Messaging (wie In-App-Nachrichten und Content Cards) abrufen. 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 REST-API-Anfragen stellen 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 Bereich 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 über den REST-API-Schlüssel, 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:
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 vorhanden und aktiv ist (zum Beispiel nicht widerrufen oder deaktiviert).
- Token-Autorisierung: Bestätigt, dass der API-Schlüssel die erforderlichen Berechtigungen für den angeforderten Endpunkt besitzt.
Wenn die Authentifizierung fehlschlägt, gibt die API eine Fehlerantwort mit einem HTTP-Statuscode zurück. Beispielsweise bedeutet 401 Unauthorized, dass der Schlüssel ungültig oder nicht vorhanden ist, 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ß- und Kleinschreibung von Anfrage-Headern
HTTP-Header-Namen sind nicht case-sensitiv, sodass Authorization und authorization gleichwertig sind. Das Gleiche gilt für andere standardmäßige Anfrage-Header wie 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 ausgegeben 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 zu 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 durch 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 entwickelt wurde – 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].