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, die Sie in Ihren Braze Campaigns referenzieren können. |
| Cloud Data Ingestion | 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: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 eine Übersicht der Begriffe, die in der Braze REST API-Dokumentation vorkommen können.
Endpunkte
Braze verwaltet eine Reihe verschiedener Instanzen für unser Dashboard und unsere REST-Endpunkte. Wenn Ihr Konto bereitgestellt wird, melden Sie sich bei einer der folgenden URLs an. Verwenden Sie den richtigen REST-Endpunkt basierend auf der Instanz, der Sie zugewiesen sind. Wenn Sie sich nicht sicher sind, eröffnen Sie ein Support-Ticket oder 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.
Verwenden Sie für die SDK-Integration den SDK-Endpunkt und 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 festgelegt haben, um die Erstellung mehrerer Profile für dieselbe Person zu vermeiden. - Braze-Nutzer-ID: Die
braze_iddient als eindeutiger Bezeichner für Nutzer:innen, der von Braze vergeben wird. Sie können diesen Bezeichner verwenden, um Nutzer:innen über die REST API zusätzlich zu external_ids zu löschen.
Weitere Informationen finden Sie in den folgenden Artikeln je nach Plattform: iOS, Android und Internet.
Ü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 auf die API über HTTPS-Webanfragen an den REST-API-Endpunkt Ihres Unternehmens zu. REST-API-Schlüssel arbeiten zusammen mit App-Bezeichner-Schlüsseln, um Daten zu tracken, darauf zuzugreifen, zu senden, zu exportieren und zu analysieren – damit alles reibungslos läuft.
Workspaces und API-Schlüssel gehören bei Braze zusammen. Workspaces sind darauf ausgelegt, Versionen derselben Anwendung über mehrere Plattformen hinweg zu verwalten. Viele Kund:innen verwenden 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 auf den Zugriff auf bestimmte Endpunkte der API beschränkt werden. Jeder API-Aufruf muss einen Schlüssel enthalten, der Zugriff auf den aufgerufenen 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 übermittelt 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 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 bestimmte Elemente wie Apps, Templates, Canvases, Campaigns, Content Cards und Segments über die API zu referenzieren. Weitere Informationen finden Sie unter API-Bezeichnertypen.
REST-API-Schlüssel erstellen
So erstellen Sie einen neuen REST-API-Schlüssel:
- Gehen Sie zu Einstellungen > APIs und Bezeichner.
- Wählen Sie API-Schlüssel erstellen.
- Geben Sie Ihrem neuen Schlüssel einen Namen zur schnellen Identifikation.
- 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 dem Erstellen eines neuen API-Schlüssels den Umfang der Berechtigungen oder die zulässigen IPs nicht mehr bearbeiten können. Diese Einschränkung dient der Sicherheit. Wenn Sie den Umfang eines Schlüssels ändern müssen, erstellen Sie einen neuen Schlüssel mit den aktualisierten Berechtigungen und verwenden Sie diesen anstelle des alten. Nachdem Sie die 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 erfassen. |
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 |
Nutzer:innen, die nur einen Alias haben, mit einer externen ID identifizieren. |
users.export.ids |
/users/export/ids |
Nutzerprofil-Informationen nach Nutzer-ID abfragen. |
users.export.segment |
/users/export/segment |
Nutzerprofil-Informationen 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 für bestehende Nutzer:innen aktualisieren. |
users.export.global_control_group |
/users/export/global_control_group |
Nutzerprofil-Informationen 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 Sperrliste setzen. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
messages.send |
/messages/send |
Eine sofortige Nachricht an bestimmte Nutzer:innen senden. |
messages.schedule.create |
/messages/schedule/create |
Einen Nachrichtenversand 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-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 |
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 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 |
Einen 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 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. |
| 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 tägliche Gesamtanzahl der 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 eindeutiger aktiver Nutzer:innen über ein rollendes 30-Tage-Fenster in einem 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 Nutzer:innen 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 |
Status der Abo-Gruppen abrufen, bei denen bestimmte Nutzer:innen explizit angemeldet oder abgemeldet sind. |
| Berechtigung | Endpunkt | Beschreibung |
|---|---|---|
sms.invalid_phone_numbers |
/sms/invalid_phone_numbers |
Ungültige Telefonnummern abfragen. |
sms.invalid_phone_numbers.remove |
/sms/invalid_phone_numbers/remove |
Die Markierung als ungültige Telefonnummer 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 bestehender REST-API-Schlüssel anzeigen oder sie löschen unter Einstellungen > APIs und Bezeichner > Tab API-Schlüssel. Beachten Sie, dass REST-API-Schlüssel nach der Erstellung nicht mehr bearbeitet werden können.
Der Tab API-Schlüssel 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 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 zeigt alle Berechtigungen dieses Schlüssels, die Whitelist-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 für AJAX-Aufrufe von Ihrer Website oder um ihn auf andere öffentliche Weise zugänglich zu machen.
Eine gute Sicherheitspraxis ist es, Nutzer:innen nur so viel Zugriff zu gewähren, wie für ihre Aufgabe notwendig ist: Dieses Prinzip kann auch auf API-Schlüssel angewendet werden, indem Sie jedem Schlüssel Berechtigungen zuweisen. Diese Berechtigungen geben 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 um ihn auf andere öffentliche Weise zugänglich zu machen.
Wenn Sie einen Schlüssel versehentlich offenlegen, können Sie ihn aus der Entwicklungskonsole löschen. Wenn Sie Hilfe bei diesem Vorgang benötigen, eröffnen Sie ein Support-Ticket.
Sicherheit von REST-API-Schlüsseln und SDK-API-Schlüsseln
REST-API-Schlüssel und SDK-API-Schlüssel haben unterschiedliche Sicherheitsprofile.
| REST-API-Schlüssel | SDK-API-Schlüssel | |
|---|---|---|
| Zweck | Serverseitige Authentifizierung für die REST API (Nachrichten senden, Daten exportieren, Nutzer:innen verwalten) | Clientseitige Identifikation für das Braze SDK (Datenaufnahme, In-App-Nachrichten, Content Cards) |
| Sichtbarkeit | Muss privat bleiben. Niemals in clientseitigem Code, öffentlichen Repositories oder Nutzeranwendungen offenlegen. | Für die Öffentlichkeit konzipiert. In Ihrem App-Binary gebündelt oder im JavaScript des Webbrowsers sichtbar, ähnlich einer Google-Analytics-Tracking-ID. |
| Lösung bei Offenlegung | Widerrufen Sie den Schlüssel sofort und erstellen Sie einen Ersatz unter Einstellungen > APIs und Bezeichner > API-Schlüssel. 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, 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 REST-API-Anfragen für einen bestimmten REST-API-Schlüssel senden dürfen. Dies wird als Allowlisting oder Whitelisting bezeichnet. Um bestimmte IP-Adressen oder Subnetze zuzulassen, fügen Sie sie beim Erstellen eines neuen REST-API-Schlüssels im Abschnitt Whitelist IPs hinzu:
Wenn Sie keine angeben, können Anfragen von jeder IP-Adresse gesendet werden.
Wenn Sie einen Braze-zu-Braze-Webhook erstellen und Allowlisting verwenden, sehen Sie sich die Liste der 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 (z. B. 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 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-Headernamen unterscheiden nicht zwischen Groß- und Kleinschreibung, 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 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, d. h. 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, der für eine bestimmte Programmiersprache – in diesem Fall Ruby – geschrieben wurde 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].