docs: document realistic sandbox passkeys#492
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-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-python studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-csharp studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli 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. |
DhruvPareek
force-pushed
the
dp/docs-realistic-sandbox-passkeys
branch
from
c761855 to
9506f09
Compare
Greptile SummaryThis PR upgrades the sandbox passkey documentation from a "magic signature" shortcut to a full, production-shaped WebAuthn registration and assertion ceremony, and adds a
Confidence Score: 4/5Safe to merge; changes are documentation-only with no functional code touched. The passkey ceremony walkthrough is a plain markdown numbered list where the Mintlify style guide calls for a mintlify/snippets/sandbox-global-account-magic.mdx — the numbered list should use
|
| Filename | Overview |
|---|---|
| mintlify/snippets/sandbox-global-account-magic.mdx | Rewrites the passkey section from a magic-value description to a full WebAuthn ceremony walkthrough; plain numbered list should use the Mintlify <Steps> component per AGENTS.md. |
| openapi/components/schemas/auth/PasskeyAssertion.yaml | Adds a clear description explaining the sandbox vs production validation split; change is accurate and well-scoped. |
| openapi.yaml | Generated bundle updated with the new PasskeyAssertion description; matches the source schema in openapi/components/schemas/auth/PasskeyAssertion.yaml. |
| mintlify/openapi.yaml | Generated Mintlify bundle updated identically to openapi.yaml; no issues. |
Sequence Diagram
sequenceDiagram
participant Dev as Developer (Browser)
participant Grid as Grid Sandbox API
participant Turnkey as Turnkey (production only)
Note over Dev,Grid: Registration
Dev->>Dev: navigator.credentials.create()
Dev->>Grid: POST /auth/credentials (challenge + attestation)
Grid-->>Dev: "credential {id}"
Note over Dev,Grid: Reauthentication
Dev->>Grid: "POST /auth/credentials/{id}/challenge (clientPublicKey)"
Grid-->>Dev: "{challenge, credentialId}"
Dev->>Dev: navigator.credentials.get(challenge, allowCredentials)
Dev->>Grid: "POST /auth/credentials/{id}/verify (assertion, Request-Id)"
Note over Grid: Sandbox: validates credentialId, challenge,<br/>origin/RP, user-presence, signature, counter
Grid-->>Dev: "{encryptedSessionSigningKey} sealed to clientPublicKey"
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
mintlify/snippets/sandbox-global-account-magic.mdx:31-35
The five-step passkey ceremony is a sequential procedure and the Mintlify style guide (AGENTS.md) explicitly says to use the `<Steps>` component for procedures and sequential instructions. Plain markdown numbering bypasses the styled step-progress rendering that Mintlify provides and is inconsistent with the rest of the docs where `<Steps>` is used for multi-step flows.
```suggestion
<Steps>
<Step title="Create a WebAuthn credential">
Generate your own WebAuthn registration challenge and call `navigator.credentials.create()`.
</Step>
<Step title="Register the passkey">
Register the passkey with `POST /auth/credentials`, passing the challenge and attestation returned by the browser.
</Step>
<Step title="Request a challenge">
Reauthenticate with `POST /auth/credentials/{id}/challenge`, passing the P-256 `clientPublicKey` that Grid should seal the session signing key to.
</Step>
<Step title="Run the browser assertion">
Pass the returned `challenge` into `navigator.credentials.get()` using the returned `credentialId` in `allowCredentials`.
</Step>
<Step title="Verify the assertion">
Verify with `POST /auth/credentials/{id}/verify`, passing the browser assertion and echoing `Request-Id` from the challenge response.
</Step>
</Steps>
```
Reviews (1): Last reviewed commit: "docs: document realistic sandbox passkey..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| 1. Generate your own WebAuthn registration challenge and call `navigator.credentials.create()`. | ||
| 2. Register the passkey with `POST /auth/credentials`, passing the challenge and attestation returned by the browser. | ||
| 3. Reauthenticate with `POST /auth/credentials/{id}/challenge`, passing the P-256 `clientPublicKey` that Grid should seal the session signing key to. | ||
| 4. Pass the returned `challenge` into `navigator.credentials.get()` using the returned `credentialId` in `allowCredentials`. | ||
| 5. Verify with `POST /auth/credentials/{id}/verify`, passing the browser assertion and echoing `Request-Id` from the challenge response. |
There was a problem hiding this comment.
<Steps> component for procedures and sequential instructions. Plain markdown numbering bypasses the styled step-progress rendering that Mintlify provides and is inconsistent with the rest of the docs where <Steps> is used for multi-step flows.
| 1. Generate your own WebAuthn registration challenge and call `navigator.credentials.create()`. | |
| 2. Register the passkey with `POST /auth/credentials`, passing the challenge and attestation returned by the browser. | |
| 3. Reauthenticate with `POST /auth/credentials/{id}/challenge`, passing the P-256 `clientPublicKey` that Grid should seal the session signing key to. | |
| 4. Pass the returned `challenge` into `navigator.credentials.get()` using the returned `credentialId` in `allowCredentials`. | |
| 5. Verify with `POST /auth/credentials/{id}/verify`, passing the browser assertion and echoing `Request-Id` from the challenge response. | |
| <Steps> | |
| <Step title="Create a WebAuthn credential"> | |
| Generate your own WebAuthn registration challenge and call `navigator.credentials.create()`. | |
| </Step> | |
| <Step title="Register the passkey"> | |
| Register the passkey with `POST /auth/credentials`, passing the challenge and attestation returned by the browser. | |
| </Step> | |
| <Step title="Request a challenge"> | |
| Reauthenticate with `POST /auth/credentials/{id}/challenge`, passing the P-256 `clientPublicKey` that Grid should seal the session signing key to. | |
| </Step> | |
| <Step title="Run the browser assertion"> | |
| Pass the returned `challenge` into `navigator.credentials.get()` using the returned `credentialId` in `allowCredentials`. | |
| </Step> | |
| <Step title="Verify the assertion"> | |
| Verify with `POST /auth/credentials/{id}/verify`, passing the browser assertion and echoing `Request-Id` from the challenge response. | |
| </Step> | |
| </Steps> |
Context Used: mintlify/AGENTS.md (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/sandbox-global-account-magic.mdx
Line: 31-35
Comment:
The five-step passkey ceremony is a sequential procedure and the Mintlify style guide (AGENTS.md) explicitly says to use the `<Steps>` component for procedures and sequential instructions. Plain markdown numbering bypasses the styled step-progress rendering that Mintlify provides and is inconsistent with the rest of the docs where `<Steps>` is used for multi-step flows.
```suggestion
<Steps>
<Step title="Create a WebAuthn credential">
Generate your own WebAuthn registration challenge and call `navigator.credentials.create()`.
</Step>
<Step title="Register the passkey">
Register the passkey with `POST /auth/credentials`, passing the challenge and attestation returned by the browser.
</Step>
<Step title="Request a challenge">
Reauthenticate with `POST /auth/credentials/{id}/challenge`, passing the P-256 `clientPublicKey` that Grid should seal the session signing key to.
</Step>
<Step title="Run the browser assertion">
Pass the returned `challenge` into `navigator.credentials.get()` using the returned `credentialId` in `allowCredentials`.
</Step>
<Step title="Verify the assertion">
Verify with `POST /auth/credentials/{id}/verify`, passing the browser assertion and echoing `Request-Id` from the challenge response.
</Step>
</Steps>
```
**Context Used:** mintlify/AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=51934046-75fb-42d3-9870-f42d61cb60e3))
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
1 participant
Summary
PasskeyAssertionschema description and regenerate the OpenAPI bundles.Stack note
Grid-Wallet-Signaturesandbox docs were split into the next PR in the stack.Testing
npm run build:openapinpm run lint:openapi(passes; existing repo warnings are still emitted)