Document external-account GET/DELETE, and fix all 85 broken curl auth examples

[shreyav]

Summary

Two things, both docs-only. Generated bundles untouched.

1. Documents GET and DELETE for a single external account — external-accounts.mdx covered create and list but neither by-id operation.
2. Fixes all 85 remaining broken curl auth examples across 17 files.

Replaces #359, which should be closed.

Part 1 — the new sections

Section	Covers
Retrieving a single external account	GET /customers/external-accounts/{externalAccountId}, full response example, 404
Deleting an external account	DELETE /customers/external-accounts/{externalAccountId}, 204, and the 409 BENEFICIARY_TRUSTED path

Why a rewrite rather than a rebase of #359. That PR has been open since April and the spec moved under it in four ways:

1. It documents a PATCH endpoint that does not exist. The path exposes only get: and delete: — verified in both the source path file and the bundled openapi.yaml. About a third of that PR describes an operation the API doesn't have.
2. "accountType": "US_ACCOUNT" is not a member of ExternalAccountType. The value is USD_ACCOUNT.
3. "accountCategory": "CHECKING" is not a field on UsdAccountInfoBase. The real field is bankAccountType.
4. Delete's contract changed. feat: document BENEFICIARY_TRUSTED (409) on customer external-account delete #770 added a 409, which docs: sync external account docs with new GET/PATCH/DELETE endpoints #359 predates.

The 409 is why the delete section earns its place. BENEFICIARY_TRUSTED fires when the account is a trusted SCA beneficiary, and the caller must untrust and confirm before delete succeeds. Nothing at the call site hints at that.

The GET example includes paymentRails because the response genuinely carries it — UsdExternalAccountInfo composes UsdAccountInfo, which requires it. A short <Info> notes it's returned rather than sent; that distinction has already caused one real bug.

Every field traces to a schema: ExternalAccount for the envelope, UsdAccountInfoBase for account fields, UsdAccountInfo for paymentRails (ACH/WIRE/RTP/FEDNOW), UsdBeneficiary for the minimum beneficiary shape.

Part 2 — the curl auth sweep

Greptile flagged the auth header on the new examples. It was right, and the problem turned out to be repo-wide: 85 curl examples across 17 files used

-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

which fails two independent ways. The single quotes stop the shell expanding the variables; and Basic auth requires base64(user:pass), not the raw pair, so the header is rejected even once expanded. Every one of these failed on copy-paste — which is the entire point of a curl example.

All 85 now use -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET".

This converges on the existing majority rather than introducing a style. api-reference/authentication.mdx documents curl -u "{client_id}:{client_secret}", and 178 examples across 40 other files already use -u. The -H form was the minority pattern.

Biggest concentrations: snippets/external-accounts.mdx (26), payouts-and-b2b/payment-flow/list-transactions.mdx (15), rewards/developer-guides/listing-transactions.mdx (8).

Verification

• 85 replacements, 85 lines added, 85 deleted — strictly 1:1, no line lost or merged
• Zero occurrences of the broken form remain
• Only auth lines changed — diff contains no other removals, so no -H 'Content-Type' was clobbered
• The 11 JS/Python Basic ${credentials} usages are untouched. Those build the header from a pre-encoded value and are correct; the sweep matched only -H lines carrying the raw credential pair
• No curl block ended up with a duplicate -u
• MDX component tags and code fences balance across every .mdx in mintlify/
• The new JSON example parses
• Generated bundles byte-identical to main

Not verified: no visual render check, and make lint was not run — it fails on main regardless, because npx spectral lint resolves to a stub spectral@0.0.0 rather than @stoplight/spectral-cli. This change touches no OpenAPI source, so the Mintlify preview is the meaningful check.

Still open in this file

external-accounts.mdx documents 21 of ~37 account types in account-types.ts. Missing: XAF, BWP, AED, BDT, EGP, GHS, GTQ, HTG, JMD, PKR, CNY, plus wallet types BASE_WALLET, POLYGON_WALLET, PLASMA_WALLET, SOLANA_WALLET, TRON_WALLET, ETHEREUM_WALLET. Out of scope here, but it's the largest remaining documentation gap in this area.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 4, 2026, 4:45 AM

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Aug 4, 2026 4:59am
grid-wallet-demo	Ignored	Preview	Aug 4, 2026 4:59am

[greptile-apps]

Greptile Summary

Adds documentation for retrieving and deleting individual external accounts.

• Provides a GET-by-ID request and complete USD external-account response example.
• Documents DELETE success and the trusted-beneficiary conflict remediation flow.

Confidence Score: 4/5

The authentication syntax in both new commands must be fixed before merging because copying either example results in an authentication failure.

The documented API behavior matches the specification, but single quoting prevents credential expansion and the raw header bypasses curl's required HTTP Basic encoding.

Files Needing Attention: mintlify/snippets/external-accounts.mdx

Important Files Changed

Filename	Overview
mintlify/snippets/external-accounts.mdx	The endpoint paths, schemas, statuses, and deletion remediation match the OpenAPI contract, but both new curl commands use a nonfunctional Basic Authentication header.

Prompt To Fix All With AI

### Issue 1
mintlify/snippets/external-accounts.mdx:1007
**Broken Basic authentication header**

When a developer copies either new command into a POSIX shell, the single quotes prevent the credential variables from expanding and curl sends an unencoded Basic header, causing the GET or DELETE request to fail authentication. Use curl's `-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"` form for both commands.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Document GET and DELETE for a single ext..." | Re-trigger Greptile}

[greptile-apps]

Broken Basic authentication header

When a developer copies either new command into a POSIX shell, the single quotes prevent the credential variables from expanding and curl sends an unencoded Basic header, causing the GET or DELETE request to fail authentication. Use curl's -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" form for both commands.

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 1007

Comment:
**Broken Basic authentication header**

When a developer copies either new command into a POSIX shell, the single quotes prevent the credential variables from expanding and curl sends an unencoded Basic header, causing the GET or DELETE request to fail authentication. Use curl's `-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"` form for both commands.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[shreyav]

Correct, and worse than described — fixed in a606eb0.

Two independent faults, not one. The single quotes stop the shell expanding the variables, as you say. But even with expansion, Authorization: Basic $ID:$SECRET is still invalid: Basic auth requires base64(user:pass), not the raw pair. So the header fails whether or not the variables expand. -u handles both.

Checked it against the rest of the docs before changing anything, and -u is the house style rather than a deviation from it:

• api-reference/authentication.mdx documents exactly this: curl -u "{client_id}:{client_secret}"
• 178 uses of -u across 40 files, versus 87 uses of the broken -H form across 17

I'd copied the -H form from the adjacent listing examples in this same file without checking it against the canonical page. My mistake.

Note this leaves the file internally inconsistent, deliberately. external-accounts.mdx has 28 occurrences of the broken form and now 2 correct ones. I've only fixed what this PR adds — converting the other 26 would bury a docs change under a mechanical sweep and make the diff hard to review.

The remaining 87 broken occurrences across 17 files are worth their own PR: every one of them fails if a developer copy-pastes it, which is the whole point of a curl example. Happy to do that sweep separately.

---

Generated by Claude Code

[greptile-apps]

Thanks for the thorough breakdown — you're right that I undersold the bug. The variable-expansion issue is the visible failure, but even a developer who correctly set environment variables would still hit a 401 because the raw ID:SECRET pair isn't base64-encoded. Two distinct failures for the cost of one wrong pattern.

The staged approach makes sense: fixing only what this PR adds keeps the diff reviewable, and a mechanical sweep of the remaining 87 occurrences is a clean, atomic PR with no logic to review. The house-style data (-u in 178 places vs 87 broken -H forms) makes the follow-up easy to justify and scope.

Fix looks good. The follow-up sweep would be a real developer-experience improvement — worth doing.