How to create a read-only Braze REST API key, add it to Medialake, and understand exactly what access it grants.
What to expect
Braze is connected with a REST API key that you create in your own Braze workspace. There is no Braze sign-in or consent screen during setup: nobody is redirected to Braze to log in. Instead, a Braze administrator creates the key, a Medialake administrator saves it in Medialake together with your workspace's REST endpoint, and Medialake calls the Braze REST API server-side from then on.
Braze has no media library API, so Medialake works from the content that uses your media. It reads your content blocks, email templates, campaigns, Canvases, and catalogs, and picks out the image and media URLs they reference. Every permission it needs is a read permission. The Braze connector does not create, edit, send, or delete anything in Braze.
Braze administrator Medialake Braze
│ create a REST API key │ │
│ with read permissions │ │
│──────────────────────────────────────────────────────────▶│
│ │ │
Medialake administrator │ │
│ save the key and REST │ │
│ endpoint as an access key │ │
│──────────────────────────────▶│ │
│ │ │
Team member │ │
│ connect and choose │ │
│ folders to sync │ │
│──────────────────────────────▶│ read-only API requests │
│ │──────────────────────────▶│
│ │ content, templates, │
│ │ campaigns, catalogs │
│ │◀──────────────────────────│
│ │ download each media │
│ │ file from its own URL │
Before you begin
You will need:
A Braze account that can create REST API keys in the workspace you want to sync
The REST endpoint for your Braze instance (Step 2 explains how to find it)
Administrator privileges in Medialake, to add the key to the Braze integration
Braze workspaces have their own REST API keys. To sync more than one workspace, create a key in each and add each one to Medialake as a separate access key.
>Keep the key private. Anyone with the key can call the Braze API with its permissions. Store it in an approved password manager or secret-management system. Do not email it, paste it into a support ticket, or commit it to source control. Medialake stores the values you enter encrypted.
Step 1: Create a REST API key in Braze
In Braze, go to Settings → APIs and Identifiers.
On the API Keys tab, click Create API Key.
Give the key a recognizable name, such as
Medialake read-only.Select only the permissions in the table below.
Leave the Whitelist IPs section empty unless your security policy requires an IP allowlist. If it does, request Medialake's current server IP addresses from [email protected] and add those. A key restricted to other addresses is rejected when Medialake uses it.
Create the key and copy it.
Permission | Folder | How Medialake uses it |
| All folders | List content blocks. Medialake also uses this call to confirm the key works, so every key needs it, even if you do not sync content blocks. |
| Content Blocks | Read each content block's content. |
| Email Templates | List email templates. |
| Email Templates | Read each template's HTML body. |
| Campaigns | List campaigns, including archived ones. |
| Campaigns | Read each campaign's messages. |
| Canvases | List Canvases, including archived ones. |
| Canvases | Read each Canvas's steps and messages. |
| Catalogs | List your catalogs. |
| Catalogs | Read the items in each catalog. |
Grant all ten even if you plan to sync only some folders. The Test button in Medialake checks every one of them, and Braze does not let you add permissions to a key after it is created.
Leave every other permission unselected, in particular anything that sends messages, tracks or exports user data, or creates and updates content. Medialake does not request or use them.
Step 2: Find your REST endpoint
Your REST endpoint depends on the Braze instance your workspace runs on. Braze's API overview lists every instance with its dashboard URL and its REST endpoint, so match the address you use to sign in to Braze against that table. For example:
Dashboard URL | REST endpoint |
|
|
|
|
If you are unsure which instance you are on, ask your Braze account manager. Use the REST endpoint, not the SDK endpoint.
Step 3: Add the key to Medialake
You need administrator privileges in Medialake for this step.
In Medialake, open Administration → Integrations from the sidebar.
Open the Braze integration.
In the Access Keys section, click Create New Setting.
In the New access key panel, give the key a Name, such as
Braze marketing workspace. The name is shown in the access key list and next to every account that connects with it.Under Credentials, fill in:
- Braze REST API key: the key from Step 1.
- Braze REST endpoint for your workspace instance: the endpoint from Step 2, including https://, for example https://rest.fra-01.braze.eu.
Under Who can use it?, choose which teams can connect Braze with this key, or make it available to all teams.
Click Save access key.
Medialake checks the format of both values before saving. The API key must be in Braze's standard key format, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, and the endpoint must be a full URL. Saving does not contact Braze.
To check the key against Braze, click Test next to it in the Access Keys list. Medialake confirms that Braze accepts the key, then tries each permission in Step 1. A detail permission, such as campaigns.details, is checked only when the workspace has at least one item of that type. If everything passes, you see "The provider accepted these credentials."
Connect Braze and choose what to sync
Any team member who can connect sources (a Team Manager or Write user), on a team that can use the access key, can add Braze as a source.
Open Connections → Catalogue from the side menu.
Find Braze and click Connect.
Under Access key, select the access key from Step 3. You can click Test to check it again.
Click Connect. There is no Braze login page: Medialake connects with the saved key.
Choose which folders to sync. Nothing is synced until you select it.
Set the Frequency. Braze syncs once a week by default. You can change this to once a day or once a month, or choose Manual.
Braze always shows the same five folders:
Folder | What Medialake reads | Media it picks up |
Content Blocks | Every content block | Images and other media referenced in HTML content blocks (image and |
Email Templates | Every email template the Braze API returns | Media referenced in each template's HTML body. |
Campaigns | Every campaign, including archived campaigns and any post-launch draft | Message image fields such as push notification images, media in email HTML and AMP bodies, and image URLs anywhere else in each message. |
Canvases | Every Canvas, including archived Canvases and any post-launch draft | The same as Campaigns, for the messages in every Canvas step. |
Catalogs | Every item in every catalog | Image URLs in any text field of an item. |
A few things are not synced:
Drag-and-drop email templates. Braze's API does not return templates built with the drag-and-drop editor, so Medialake cannot see them.
Personalized media URLs. A URL built with Liquid (containing
{{or{%) has no fixed address, so it is skipped.Some in-app message and Content Card images. Braze has no dedicated image field for these channels, so Medialake looks for image URLs in the message text. An image whose URL does not end in a recognized image extension may be missed.
Each synced file records where it was found: the content block, template, campaign, Canvas, or catalog, its name and Braze tags, the message channel, and whether the file is hosted by Braze.
Limiting what Medialake can access
The key's permissions are the main control. With only the read permissions in Step 1, the key cannot change anything in your workspace, even if it is compromised.
The key reaches the whole workspace it belongs to. Choosing folders in Medialake controls what is synced, but it does not narrow the key itself. If you need tighter control over where the key can be used from, add Medialake's server IP addresses to the key's Whitelist IPs when you create it (see Step 1).
What Medialake can and cannot do
With the permissions above, Medialake can:
List and read your content blocks, email templates, campaigns, Canvases, and catalog items
Download the images and media those items reference, from their own URLs
Medialake cannot:
Send messages, or launch, pause, or stop campaigns and Canvases
Create, edit, or delete content blocks, templates, campaigns, Canvases, or catalogs
Read, track, or export user profiles, segments, or analytics
See drag-and-drop email templates
Medialake sends your API key only to the REST endpoint you entered. Media files are downloaded from their own addresses, whether Braze hosts them or not, without the key.
Staying connected
There is no token to refresh: Medialake uses the same key for every sync. If Braze rejects the key during a sync, Medialake checks it again, and if Braze still rejects it, the connection is marked as unauthorized. This happens when the key is deleted in Braze, or when an IP allowlist on the key does not include Medialake's servers.
If a single permission is missing, only the folder that needs it fails to sync, and the other folders keep working. The exception is content_blocks.list: Medialake uses it to check the key, so a key without it can cause the whole connection to be marked as unauthorized.
Catalog items are read more slowly than other content. Braze limits catalog item requests to 50 per minute, and Medialake paces its catalog requests to stay under that limit. For all other requests, Medialake retries automatically when Braze reports a rate limit or a temporary error.
To replace a key, create a new one in Braze with the same permissions, add it in Medialake as a new access key, and switch the connection to it. To switch, open the source's General tab, click Change Key in its Access Keys section, select the new key, and click Save. You can delete the old access key in Medialake once no connection uses it.
Revoking access
To revoke Medialake's access, go to Settings → APIs and Identifiers in Braze. On the API Keys tab, hover over the key created for Medialake and select Delete. Medialake's requests fail from that moment.
Remove the Braze connection in Medialake as well if it should no longer sync, then delete its access key from the Access Keys list.
Troubleshooting
Symptom | What to check |
"The Braze REST API key format is invalid." when saving | Paste the REST API key from the API Keys tab, with no spaces. App and SDK identifiers are not REST API keys. |
"The Braze REST endpoint for your workspace instance must be a valid URL." when saving | Enter the full endpoint including |
Test shows "The provider rejected these credentials." | The key may be wrong or deleted, or it may be missing |
Test shows "Missing Braze permission for" followed by an API path | The key lacks the permission for that path, for example |
Test shows "These credentials look right, but the provider couldn't confirm them just now." | Braze could not be reached or was rate-limiting. Try again in a few minutes. |
One folder fails to sync while the others work | The key is missing that folder's permissions. This can pass Test if the workspace had no items of that type when you tested. |
An email template's images are missing | The template was probably built with the drag-and-drop editor, which the Braze API does not return. |
A personalized image is missing | URLs built with Liquid are skipped by design. |
A catalog sync is slow | Medialake is pacing requests to stay within Braze's limit of 50 catalog item requests per minute. No action is needed. |
The connection is marked as unauthorized | The key was deleted, or an IP allowlist is blocking Medialake. Create a new key and switch the connection to it. |
If the issue continues, contact [email protected] with your REST endpoint, the folders you selected, and the error message. Do not include the API key.
Further reading
Braze API overview: REST API keys, permissions, IP allowlisting, and the list of instances and REST endpoints
List available email templates: the email template endpoint, including its note on drag-and-drop templates
Questions about connecting Braze? Contact [email protected].
