docs: align auth endpoint docs with PDF#481
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
✱ Stainless preview builds for gridThis PR will update the cli csharp go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-cli studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-php studio · code · diff
✅ grid-python studio · code · diff
✅ grid-csharp studio · code · diff
✅ grid-typescript studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
Summary: - Update Global Accounts docs for default EMAIL_OTP bootstrap and signed-retry passkey/OAuth registration. - Document session refresh and customer email update signing paths from the auth endpoints PDF. - Replace raw signature guidance with full Turnkey API-key stamp guidance for Grid-Wallet-Signature. - Update quote execute and session refresh OpenAPI examples, then rebuild bundled specs. Test Plan: - make build - npm run lint - git diff --check - targeted rg stale-pattern scans
DhruvPareek
force-pushed
the
docs-auth-pdf-endpoint-followups
branch
from
9be10e9 to
5078263
Compare
Greptile SummaryThis documentation-only PR aligns the Global Accounts auth docs with the auth endpoints PDF, replacing raw base64-signature guidance with full Turnkey API-key stamp guidance across OpenAPI specs and MDX snippets.
Confidence Score: 5/5This is a documentation-only change with no application code; the risk of merging is limited to reader confusion from a few stale phrases that already have open comments. All changed files are OpenAPI YAML descriptions and MDX documentation snippets — no executable logic is modified. The stamp format, code examples across TypeScript/Kotlin/Swift, and the new session-refresh prose are self-consistent. The two carry-over issues are documentation wording gaps already captured in prior review comments, not new regressions. openapi/paths/auth/auth_sessions_{id}_refresh.yaml — the Grid-Wallet-Signature parameter example at line 47 and the description wording were not fully updated; mintlify/snippets/global-accounts/concepts.mdx line 15 still uses the old "base64 signature" phrasing.
|
| Filename | Overview |
|---|---|
| openapi/paths/auth/auth_sessions_{id}_refresh.yaml | payloadToSign example updated to alphabetical key order, but the Grid-Wallet-Signature parameter example (line 47) still uses the stale stamp format (wrong scheme name P256_ECDSA_SHA256 and wrong field order); description at line 15 also retains 'Sign payloadToSign' while all other updated docs say 'Stamp'. |
| mintlify/snippets/global-accounts/concepts.mdx | Table rows and flow summary paragraph updated to Turnkey stamp terminology, but the 'Outgoing funds' bullet (line 15) still reads 'passes the base64 signature as the Grid-Wallet-Signature header' — inconsistent with every other updated page. |
| mintlify/snippets/global-accounts/authentication.mdx | Correctly documents the signed-retry pattern for passkey and OAuth registration, updates mermaid diagrams with the 202 step, and replaces all base64 signature examples with Turnkey stamp examples. |
| mintlify/snippets/global-accounts/client-keys.mdx | Old noble/curves raw ECDSA signing replaced with Turnkey api-key-stamper approach across TypeScript, Kotlin, and Swift; stamp JSON structure and base64url encoding look correct and consistent across all three implementations. |
| mintlify/snippets/global-accounts/managing-sessions.mdx | New 'Refresh a session' section added with correct two-step signed-retry curl examples and updated stamp header value; session revocation section also updated from sign to stamp terminology. |
| mintlify/snippets/global-accounts/walkthrough.mdx | Step 3 correctly replaced with 'find the default email OTP credential' flow and steps 7-8 updated for EMAIL_OTP; minor indentation drift on the instructionsNotes key in the quote response example. |
| openapi/paths/quotes/quotes_{quoteId}_execute.yaml | Grid-Wallet-Signature description updated from 'base64-encoded' to 'full Turnkey API-key stamp' and example replaced with correct stamp format. |
| openapi/paths/agents/agents_me_quotes_{quoteId}_execute.yaml | Same Grid-Wallet-Signature description and example update as the non-agent execute path; consistent with the other execute endpoint. |
| openapi/components/schemas/common/PaymentEmbeddedWalletInfo.yaml | payloadToSign description updated from 'signature is base64-encoded' to 'resulting Turnkey API-key stamp is passed'; consistent change. |
| mintlify/snippets/global-accounts/exporting-wallet.mdx | sign/signature terminology updated to stamp throughout the export flow; curl examples now use the Turnkey stamp header value. |
Sequence Diagram
sequenceDiagram
participant C as Client
participant IB as Integrator Backend
participant G as Grid
Note over C,G: Session Refresh (new in this PR)
C->>IB: clientPublicKey (fresh P-256)
IB->>G: "POST /auth/sessions/{id}/refresh { clientPublicKey }"
G-->>IB: "202 { payloadToSign, requestId, expiresAt }"
IB-->>C: "{ payloadToSign, requestId }"
C->>C: buildGridWalletSignature(payloadToSign, sessionPrivateKey)
C->>IB: "{ stamp, requestId }"
IB->>G: "POST /auth/sessions/{id}/refresh Grid-Wallet-Signature: stamp, Request-Id: requestId"
G-->>IB: "201 AuthSession { encryptedSessionSigningKey }"
IB-->>C: encryptedSessionSigningKey
C->>C: decrypt with clientPrivateKey to get new sessionSigningKey
Note over C,G: Passkey / OAuth Registration (signed-retry)
IB->>G: "POST /auth/credentials { type, ... }"
G-->>IB: "202 { payloadToSign, requestId, expiresAt }"
IB-->>C: "{ payloadToSign, requestId }"
C->>C: stamp(payloadToSign, existingSessionPrivateKey)
C->>IB: "{ stamp, requestId }"
IB->>G: Same POST Grid-Wallet-Signature: stamp, Request-Id: requestId
G-->>IB: 201 AuthMethod
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
openapi/paths/auth/auth_sessions_{id}_refresh.yaml:15-16
The description says "Sign `payloadToSign`" but then immediately calls the result "the full API-key stamp" — mixing the old raw-ECDSA verb with the new Turnkey stamp terminology. Every other updated description in this PR uses "stamp" or "build a Turnkey API-key stamp over" as the verb. A developer reading only this endpoint's description gets a conflicting picture of what the operation is.
```suggestion
2. Build a Turnkey API-key stamp over `payloadToSign` with the current
session signing key, then retry the same request with that stamp as
`Grid-Wallet-Signature`, the
```
### Issue 2 of 2
mintlify/snippets/global-accounts/walkthrough.mdx:221
The `instructionsNotes` key picked up two extra spaces of indentation in this edit, putting it at 8 spaces while its sibling keys in the same JSON object are at 6. The rendered code block will look misaligned for readers.
```suggestion
"instructionsNotes": "Stamp the payloadToSign byte-for-byte and pass the stamp as the Grid-Wallet-Signature header on execute"
```
Reviews (2): Last reviewed commit: "docs: align auth endpoint docs with PDF" | Re-trigger Greptile
2 participants
Summary
EMAIL_OTPbootstrap and signed-retry passkey/OAuth registration.Grid-Wallet-Signature.Test Plan
make buildnpm run lintgit diff --checkrgstale-pattern scans for old auth identifiers, request IDs, payload shapes, and raw wallet signature examples.