Sync docs with auth credential contract changes

[claude]

Summary

• Remove email field from EMAIL_OTP credential request examples in authentication.mdx (credential now uses customer email automatically per PR Align auth credential create contract #444)
• Fix walkthrough.mdx incorrect claim that POST /auth/credentials 201 response includes challenge, requestId, and expiresAt (those fields come from /challenge endpoint, not registration)
• Update scripts/README.md step 1.4 to verify existing auto-created EMAIL_OTP credential instead of trying to create a new one
• Update CLAUDE.md gotcha note to say "verify" instead of "register"

These changes align documentation with the API contract changes from:

• Align auth credential create contract #444 Align auth credential create contract
• Align auth session request-id contract #445 Align auth session request-id contract

Test plan

• Run make lint to verify OpenAPI and markdown
• Review EMAIL_OTP examples no longer include email field
• Review scripts/README.md step 1.4 uses /challenge instead of POST /auth/credentials

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 9, 2026, 8:46 AM

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 9, 2026 8:44am

[greptile-apps]

Greptile Summary

This PR syncs four documentation files with API contract changes from PRs #444 and #445, removing the email field from EMAIL_OTP credential examples and correcting a false claim in the walkthrough about the 201 response from POST /auth/credentials.

• authentication.mdx: Removes email from the sequence diagram and three curl snippets correctly, but one prose sentence ("to the address you pass") was not updated and now contradicts the new behaviour where Grid derives the address from the customer record automatically.
• walkthrough.mdx: Accurately strips the incorrect mention of challenge, requestId, and expiresAt from the credential-registration 201 response description.
• scripts/README.md / CLAUDE.md: Step 1.4 is rewritten to look up the auto-created credential and issue a challenge; CLAUDE.md gotcha is updated to match.

Confidence Score: 4/5

Documentation-only PR that is mostly correct, but one prose sentence in authentication.mdx still describes the old behaviour and should be updated before merge.

The authentication.mdx prose on line 423 still says "to the address you pass" after removing email from the request body, leaving a contradiction that developers reading the docs would notice. All other changes are accurate and consistent with the described contract updates.

mintlify/snippets/global-accounts/authentication.mdx — the prose intro for Email OTP registration needs its wording updated to match the removed email field.

Important Files Changed

Filename	Overview
mintlify/snippets/global-accounts/authentication.mdx	Removes email from three EMAIL_OTP curl examples and the sequence diagram — correct per the contract change — but the prose intro on line 423 still says "to the address you pass," which now contradicts the updated API.
mintlify/snippets/global-accounts/walkthrough.mdx	Removes the incorrect claim that POST /auth/credentials 201 includes challenge/requestId/expiresAt fields; those fields belong to the /challenge endpoint. Change is accurate and clean.
scripts/README.md	Step 1.4 now lists the existing EMAIL_OTP credential and issues a /challenge instead of POSTing to create one; script logic is functionally correct but lacks a guard for an empty CRED_ID.
CLAUDE.md	One-line update to match the new bootstrap terminology ("Verify" instead of "Register"); no issues.

Sequence Diagram

sequenceDiagram
  participant C as Client
  participant IB as Integrator backend
  participant G as Grid
  participant E as Email

  Note over C,E: Old flow (before this PR)
  C->>IB: "POST /my-backend/otp/register { email }"
  IB->>G: "POST /auth/credentials { type: EMAIL_OTP, accountId, email }"
  G->>E: deliver OTP email
  G-->>IB: 201 AuthMethod

  Note over C,E: New flow (after this PR)
  C->>IB: "POST /my-backend/otp/register { email }"
  IB->>G: "POST /auth/credentials { type: EMAIL_OTP, accountId }"
  Note right of G: Grid uses email from customer record automatically
  G->>E: deliver OTP email
  G-->>IB: 201 AuthMethod

Loading

Comments Outside Diff (1)

1. mintlify/snippets/global-accounts/authentication.mdx, line 423 (link)

   The prose intro for "Email OTP registration" still says "to the address you pass," but email was just removed from the credential request body — the address is now taken automatically from the customer record, so nothing is being "passed."

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: mintlify/snippets/global-accounts/authentication.mdx
   Line: 423
   
   Comment:
   The prose intro for "Email OTP registration" still says "to the address you pass," but `email` was just removed from the credential request body — the address is now taken automatically from the customer record, so nothing is being "passed."
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
mintlify/snippets/global-accounts/authentication.mdx:423
The prose intro for "Email OTP registration" still says "to the address you pass," but `email` was just removed from the credential request body — the address is now taken automatically from the customer record, so nothing is being "passed."

```suggestion
Creating the credential triggers an OTP email to the address on the customer record. The user reads the code off the email and submits it through your UI.
```

### Issue 2 of 2
scripts/README.md:92-95
If no `EMAIL_OTP` credential is found (e.g., `$USDB_ACCT` is unset or the auto-provisioned credential hasn't appeared yet), `$CRED_ID` will be empty and the challenge request will hit `/auth/credentials//challenge`, producing a confusing 404 or routing error. A guard prevents silent failures in a dev walkthrough script.

```suggestion
CRED_ID=$(g "$GRID_BASE_URL/auth/credentials?accountId=$USDB_ACCT" \
  | jq -r '.data[] | select(.type=="EMAIL_OTP") | .id | first // empty')

[ -z "$CRED_ID" ] && echo "ERROR: no EMAIL_OTP credential found for $USDB_ACCT" && exit 1

g -X POST "$GRID_BASE_URL/auth/credentials/$CRED_ID/challenge"
```

_{Reviews (1): Last reviewed commit: "Sync docs with auth credential create co..." | Re-trigger Greptile}

[greptile-apps]

If no EMAIL_OTP credential is found (e.g., $USDB_ACCT is unset or the auto-provisioned credential hasn't appeared yet), $CRED_ID will be empty and the challenge request will hit /auth/credentials//challenge, producing a confusing 404 or routing error. A guard prevents silent failures in a dev walkthrough script.

Suggested change

	CRED_ID=$(g "$GRID_BASE_URL/auth/credentials?accountId=$USDB_ACCT" \
	| jq -r '.data[] | select(.type=="EMAIL_OTP") | .id')
	g -X POST "$GRID_BASE_URL/auth/credentials/$CRED_ID/challenge"
	CRED_ID=$(g "$GRID_BASE_URL/auth/credentials?accountId=$USDB_ACCT" \
	| jq -r '.data[] | select(.type=="EMAIL_OTP") | .id | first // empty')
	[ -z "$CRED_ID" ] && echo "ERROR: no EMAIL_OTP credential found for $USDB_ACCT" && exit 1
	g -X POST "$GRID_BASE_URL/auth/credentials/$CRED_ID/challenge"

Prompt To Fix With AI

This is a comment left during a code review.
Path: scripts/README.md
Line: 92-95

Comment:
If no `EMAIL_OTP` credential is found (e.g., `$USDB_ACCT` is unset or the auto-provisioned credential hasn't appeared yet), `$CRED_ID` will be empty and the challenge request will hit `/auth/credentials//challenge`, producing a confusing 404 or routing error. A guard prevents silent failures in a dev walkthrough script.

```suggestion
CRED_ID=$(g "$GRID_BASE_URL/auth/credentials?accountId=$USDB_ACCT" \
  | jq -r '.data[] | select(.type=="EMAIL_OTP") | .id | first // empty')

[ -z "$CRED_ID" ] && echo "ERROR: no EMAIL_OTP credential found for $USDB_ACCT" && exit 1

g -X POST "$GRID_BASE_URL/auth/credentials/$CRED_ID/challenge"
```

How can I resolve this? If you propose a fix, please make it concise.