Connect Claude to Braze: the read-only-first setup

Two values move between the systems. The first is a REST API key, generated inside Braze under Settings, then APIs and Identifiers. The second is your REST endpoint — Braze runs workspaces across many clusters, and yours has its own hostname, something in the shape of rest.iad-01.braze.com. Braze shows the correct one for your account in its own API documentation. Point a valid key at the wrong cluster and you get an authorisation error that reads exactly like a bad key, which is why more setup time is lost to the endpoint than to the credential.

In Orbit those two arrive as braze_api_key and braze_endpoint, pasted once into the extension's settings in Claude Desktop. They sit in that local config on your machine; calls run from there to Braze's API. After that, Claude reaches for Braze when a job needs it rather than describing Braze from memory — which is the actual difference, and the subject of the with-Orbit versus without comparison.

The part worth slowing down on is the permission list. Braze grants API access per endpoint family, as individual checkboxes on the key itself — campaigns.list, canvas.details, messages.send, and so on, each ticked or not ticked at creation. There is no role, no least-privilege default, and no confirmation prompt at call time. Whatever you tick is what the model can do, silently, from the first message.

The first key you make should be able to answer questions and unable to change anything. Not because the model is reckless, but because a read-only credential makes an entire category of accident structurally impossible: a misread instruction becomes a wasted API call rather than a message in somebody's inbox. You can always issue a second key later. You cannot un-send.

Two keys rather than one is the setup worth copying: an audit key carrying only reads, and a build key carrying reads plus template and content-block writes. Separately named, separately revocable. When the build work finishes you retire the build key and the audits keep running — which is the whole point of naming them properly in the first place.

Braze also lets you restrict an API key so it only works from a set of source IPs. If your team works from a fixed egress address it costs nothing to add, and it turns a leaked key into an unusable one.

The read half of the integration is not the consolation prize. Most of the work you would actually want a model doing in Braze is reading, comparing, and grading — jobs that are tedious by hand and quick against an API.

Pre-launch QA on a Canvas. Read the live Canvas structure — entry rules, audience filters, message-template bindings, delays, conversion events, exit criteria, frequency caps — and check it line by line against what the brief said it would be. Orbit's Canvas QA skill runs this as a severity-rated checklist that returns a go or no-go call, keeps entry on a test audience throughout, and launches nothing.

Template and Liquid audits. Pull every email template and read the actual bodies rather than the ones somebody remembers writing. Missing fallbacks, orphaned personalisation tags, and branches nobody has rendered are all visible in the source once you can list it. The Braze Liquid reference covers what to look for.

Segment reads. Inventory every segment, flag the ones nobody has used in a year, find the pairs that overlap so heavily they should be one, and chart size over time. That is a different exercise from designing segments well, which the segmentation guide handles.

Naming-convention enforcement. A convention nobody can audit is a document, not a standard. An inventory read is what makes it enforceable — you cannot grade names you cannot list. Read the whole workspace, grade every asset against the convention, and produce a rename plan for the ones that fail. The naming conventions guide covers the convention itself.

Data-model validation. Before a program ships, confirm the custom events and attributes its logic depends on exist in the live workspace with the names the brief assumed. This is the check that catches a launch built on an attribute that was renamed nine months ago. See custom attributes design for how those names drift.

Run together, those reads produce one artefact rather than five conversations — a workspace inventory with the duplicates, stale assets and off-convention names already flagged.

Orbit's write tools against Braze are narrow on purpose: publish content blocks and compiled email templates, upload images into the media library, and fire a test send at a designated test list. Those are reversible or contained. A template you publish can be republished; an image in the media library is inert until something references it.

The test send deserves a note because Braze is unusual here. Its messaging endpoint can target a designated test list directly, so a test send is a real Braze send rather than a local HTML preview — a genuine advantage over ESPs that expose no test-send endpoint at all, and one of the reasons Braze is the deepest of Orbit's integrations. It is still a send. Keep that test list to addresses you own and check its membership before you use it, because the endpoint does not care whether the list drifted.

One special case is worth understanding rather than working around: large parts of Canvas configuration are not writable through the public API at all, which is why the deep-edit path runs through the Braze dashboard in a browser instead. Treat that path as manual work with a person watching each save, not as automation with a longer script. The API's limits are doing you a favour there.

A green connection tick tells you a credential authenticated. It does not tell you which permissions came with it, which workspace it points at, or whether the model is reading the program you think it is. Four checks, in this order.

Start with the auth probe, and know what it cannot distinguish. Braze publishes no dedicated ping endpoint, so any connection check has to be a real read — Orbit probes with a cheap GET on the email template list, limited to one result. A pass means the key and the endpoint are both live. A failure does not separate a bad key from the wrong cluster, so check the endpoint hostname first; it is the more common mistake.

Match the counts against the dashboard. Ask for an inventory of Canvases, campaigns, segments and templates, then compare the totals to what Braze shows you. A key missing canvas.list does not announce itself — it returns a short list. Silence is the failure mode that costs you an afternoon of analysis on a partial picture.

Prove the withheld permissions actually fail. Ask for something you deliberately did not grant and check you get an authorisation error rather than a result. A permission you believe you withheld and never tested is a permission you are assuming. This takes one message and is the only evidence that the read-only key is read-only.

Check which workspace the key points at. Braze API keys are scoped to a single workspace. A key from staging reads cleanly, returns sensible data, and describes a program that is not the one you are about to ship. Check that an asset name you recognise from production appears in the inventory before you trust anything built on top of it.

Then re-run the first two whenever someone rotates a key or you add a workspace, because both invalidate the check without raising an error. If you are still deciding whether Braze is the right platform to be doing this against, the ESP comparison covers where it sits against the alternatives, and the Braze IP warm-up guide covers the one piece of setup no API will do for you.

The short version to take into Monday: make a read key, name it after its job, verify a withheld permission genuinely fails, and only issue a write credential once you have a specific job for it. Everything in this guide is recoverable except a send.