[cathalging]

Why?

The Brands and IP allowlist reference pages don't say which OAuth scope each operation needs, so an app without it gets a 401 the docs never mention. The retrieve-brand 404 example also shows the wrong error code, and the update-allowlist page doesn't say which fields are optional or which addresses are accepted.

How?

Adds the required scope and a missing-scope 401 example to each operation, fixes the brand 404 code, and documents the optional fields and the IPv4-only rule on the allowlist update, in both 2.17 and Preview.

_{Generated with Claude Code}

[yasser-aboelgheit-intercom]

Thanks Cathal. I checked these against the API's behaviour and they all hold:

• the read_brands and manage_ip_allowlist scopes;
• a missing scope returning 401 token_unauthorized "Not authorized to access resource";
• the brand 404 code brand_not_found;
• both allowlist fields being optional, with an empty request returning the current settings unchanged;
• blank entries being dropped and whitespace trimmed;
• non-IPv4 entries returning 422 parameter_invalid.

Both specs parse with no dangling refs, and fern check shows 0 errors and the same 317 warnings as main.

One question: the description says Preview has no IP allowlist operations, but Preview does have getIpAllowlist and updateIpAllowlist (under /ip_allowlist in descriptions/0), and the API has served them since 2.14. At this head the Preview copies still lack the scope line, the missing-scope 401 example, and the optional-fields and IPv4 paragraphs. Preview feeds the SDKs, so would it be worth adding the same edits there?

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks for this. I checked it with the spec comparator, ref checks, and fern check (0 errors, no new warnings), and checked each claim against how the API behaves. The scopes, the missing-scope 401, brand_not_found and the IPv4-only rule all match.

A few questions:

1. Preview IP allowlist — The PR says Preview has no IP allowlist operations, but descriptions/0 has /ip_allowlist with both getIpAllowlist and updateIpAllowlist. Should the scope lines, the missing-scope 401 example, the optional-fields text and the IPv4 rule go there too, so Preview doesn't fall behind 2.17?
2. Empty update — "A request with neither returns the current settings without changing anything" is right in practice, and sending null for a field counts as omitting it. Should the description say that too?
3. Merge order — This conflicts with #747 in the 2.17 spec, so whichever lands second will need a rebase.

Holding approval for item 1.

~ Automated via Claude

[cathalging]

Thanks Yasser, good catch.

1. The Preview IP allowlist operations arrived with Align Preview and 2.17 specs with what the API sends and accepts #735 after I first checked, and I missed them on the rebase. Preview now gets the same scope lines, missing-scope 401 example, optional-fields text and IPv4 rule as 2.17, and I've corrected the description.
2. Added "Sending null for a field is the same as omitting it."
3. Noted. I'll rebase whichever of these lands second.

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks Cathal, the Preview IP allowlist operations now get the same scope lines, missing-scope 401 example, optional-fields text and IPv4 rule as 2.17, and the null sentence matches how the API treats a null field. Re-checked the new head: the edit is the same in both versions, and both specs parse with no dangling refs.

~ Automated via Claude