What a read-only Braze key already buys you — and where its ceiling actually is

There is no OAuth flow when you connect a model to Braze. No consent screen listing what it may do, no app to install, no per-call approval. You create a REST API key — a bearer token with no user identity attached — tick a set of permission boxes and paste the key and your cluster endpoint into a config field. From that point the integration can reach exactly what you granted. Braze cannot tell a model from a script from an intern. The token is the identity.

The default instinct is to tick everything, because the alternative is coming back to the key screen later. Resist it, and not for the reason people usually give. This is not about whether the model is reckless. It is about which mistakes are recoverable.

A read credential turns an entire category of accident into a wasted API call. A misparsed instruction, a hallucinated Canvas ID, a request that meant one workspace and hit another — on a read key, every one of those produces a wrong answer you can notice and correct. On a key with messages.send ticked, one of them produces an email in somebody's inbox at API speed with no review step between the instruction and the delivery. You can re-run a query. You cannot un-send.

The useful framing is not "read-only is the safe subset". It is that read-only is where most of the work you would want a model doing already lives. An inventory pull against a Braze workspace hits seven endpoint families, and between them they describe the whole program:

Stack a few of those together and you can answer questions that normally take an afternoon of clicking. Which content blocks are referenced by nothing. Which segments overlap so heavily they are the same audience with two names. Whether the custom attribute a new program's branch logic depends on exists in the workspace at all, or exists only in the spec. Whether the naming convention people agreed on in a meeting survived contact with the last six months.

That last one sounds cosmetic and is not. A Canvas called "Test 2 FINAL (new)" costs nothing today and costs an hour of archaeology the first time someone asks whether it is safe to archive.

The rule that makes an audit worth running before anything else: you cannot build well on a foundation you have not inspected. Handing a model write access to a workspace nobody has inventoried is asking it to make confident changes to a system neither of you understands.

Here is the part that changes how you plan the work. The limits you hit first are not permission limits. They are gaps in what the Braze API exposes at all, and no checkbox opens them.

Read that list against what a Canvas actually is and the consequence is uncomfortable. The API can tell you a journey exists, how many steps it has and what templates are in the workspace. It cannot tell you which template is bound to step four, which users take the paid branch, how long the delay before the second email is, or which conversion event the whole thing is measured on. Those are the things that go wrong.

So "we verified the Canvas over the API" is not a claim that survives inspection. What it usually means is that someone confirmed a structure and inferred the rest. The honest method is a browser: open the Canvas Flow editor, click through each gate and each step, then read the configuration off the screen — using API reads to corroborate rather than replace it. Fetching a template by ID and fingerprinting it by subject line, preheader and one distinctive block will tell you whether the thing bound to that step is the one you meant. That is a real corroboration. It is not a substitute for looking.

The upside of knowing where the ceiling sits is that you stop trying to buy your way past it with permissions. Seeing a delay duration needs no write scope at all. They need to open the Canvas.

At some point a real job needs write scope — publishing a template, uploading images, firing a test send. Issue a second key then, for that job, rather than upgrading the first one. Four things are worth doing first, in this order.

Prove a withheld permission actually fails. Ask for something you deliberately did not grant and confirm you get an authorisation error rather than a result. A permission you believe you withheld and never tested is a permission you are assuming. It takes one message, and it is the only evidence you will ever have that the read key is genuinely read-only.

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

Name each key after its job. claude-audit-read, not API key 4. The label is the only thing that makes one key revocable without breaking the others, and Braze shows the secret once — so copy it when it appears.

Add the IP restriction if you can. Braze lets you restrict a key so it works only from a set of source addresses. If your team has a fixed egress address it costs nothing and turns a leaked key into an unusable one.

The one permission worth arguing about is messages.send and the Canvas and campaign trigger scopes. A send is irreversible, runs at API speed and has no review step. The version worth enabling is a test send to addresses you own — and even that deserves a look at the recipient list before each use, because "test list" is a name, not a guarantee.

The full checkbox-by-checkbox breakdown, including which scopes to grant on day one and which to leave alone permanently, is in the connection guide.

Connect read-only. Run the inventory before you ask a single question about the program, because every judgement after that depends on knowing what is actually in there. Take the naming and orphan findings seriously even though they feel like housekeeping — they are the cheapest signal you will get about how much of the workspace anyone still understands.

Then, when you reach a Canvas that matters, accept that the last mile is a browser and budget for it rather than pretending the API closed the gap. That acceptance is what separates a QA pass that catches a mis-bound template from one that produces a confident green tick over a journey nobody opened. Which Canvas checks a machine should own covers where that line falls.

And keep the wider frame in view: everything a read key gives you is a description of a system whose canonical copy is currently a dashboard. Auditing it is worth doing. Leaving it as the only home for your program is the deeper problem, and the source-of-truth argument is the fix.

Monday version: make one key, tick only reads, name it after its job and prove that a scope you withheld genuinely errors. Everything you do after that is recoverable except a send.