docs: document realistic sandbox passkeys

[DhruvPareek]

Summary

• Document the sandbox passkey flow as a real WebAuthn registration/assertion ceremony instead of only the legacy magic signature.
• Call out the sandbox validation behavior for credential ID, challenge, origin/RP binding, user presence, assertion signature, and signature counter.
• Add a PasskeyAssertion schema description and regenerate the OpenAPI bundles.
• Preserve the Stainless workflow change that makes preview/merge builds use .stainless/stainless.yml from this repo.

Stack note

• The sandbox email OTP inbox docs PR was removed from the stack; email OTP docs continue to use the fixed sandbox code 000000.
• Real Grid-Wallet-Signature sandbox docs are split into the next PR in the stack.

Testing

• npm run build:openapi
• npm run lint (passes; existing repo warnings are still emitted)

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	May 29, 2026 11:24pm

[DhruvPareek]

• docs: document real sandbox wallet signatures #494
• docs: document realistic sandbox passkeys #492 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

csharp

docs(types): add descriptions to PasskeyAssertion and PasskeyCredentialVerifyRequestFields

go

docs(api): add documentation for passkey assertion parameters

kotlin

docs(api): add documentation to passkey credential models

openapi

docs(types): add description to PasskeyAssertion model

php

docs(types): add descriptions to passkey assertion in auth credentials

python

docs(types): add docstrings to passkey assertion types

ruby

docs(api): add documentation for assertion field in auth passkey models

typescript

docs(types): document passkey assertion in auth credentials

✅ grid-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ grid-ruby studio · code

Your SDK build had at least one note diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️ grid-kotlin studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ❗

✅ grid-typescript studio · code

Your SDK build had at least one note diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/4bbc90c878b58f252944ebf592e37964bd60ef4f/dist.tar.gz

⚠️ grid-python studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/2bc80ace3f324d0f62e2f3b860944d3872c8ddac/grid-0.0.1-py3-none-any.whl

⚠️ grid-csharp studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ✅ → test ❗

⚠️ grid-go studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@910cd3a45574d2c17590b3f3e24a88e969cbea97

✅ grid-php studio · code

Your SDK build had at least one note diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️ grid-cli studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ❗ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-30 00:22:09 UTC

[greptile-apps]

Greptile Summary

This PR upgrades the sandbox passkey documentation from a "magic signature" shortcut to a full, production-shaped WebAuthn registration and assertion ceremony, and adds a description field to the PasskeyAssertion OpenAPI schema.

• The sandbox-global-account-magic.mdx snippet is rewritten to walk developers through the five-step WebAuthn flow (create → register → challenge → get → verify), with the legacy sandbox-valid-passkey-signature value demoted to a backward-compatibility <Note>.
• The PasskeyAssertion schema gains a description that clarifies sandbox vs. production validation responsibilities (Grid vs. Turnkey), and both generated bundles (openapi.yaml, mintlify/openapi.yaml) are regenerated to match.

Confidence Score: 4/5

Safe 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 <Steps> component — a minor presentation inconsistency, but nothing that breaks the docs or misleads developers about the API behavior.

mintlify/snippets/sandbox-global-account-magic.mdx — the numbered list should use <Steps> per the Mintlify component guide.

Important Files Changed

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"

Loading

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}

[pengying]

LGTM just the greptile comment

[pengying]

greptile comment

[DhruvPareek]

Merge activity

• May 30, 12:13 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 30, 12:13 AM UTC: Graphite couldn't merge this PR because it failed for an unknown reason.
• May 30, 12:15 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 30, 12:15 AM UTC: @DhruvPareek merged this pull request with Graphite.