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.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 28, 2026 9:50pm

[DhruvPareek]

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.
Learn more

• docs: document real sandbox wallet signatures #494
• docs: document realistic sandbox passkeys #492 👈 (View in Graphite)
• docs: add sandbox email OTP inbox endpoint #489
• docs: explain realistic OIDC sandbox tokens #487 : 1 other dependent PR (#488 )
• docs: align auth endpoint docs with PDF #481
• docs: allow multiple passkey credentials #479
• docs: update auth signed retry examples #477
• docs: fix auth account identifiers #476
• 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

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ grid-ruby studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ✅

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ❗

✅ grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ✅

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

✅ grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

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

✅ grid-csharp studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ❗ → lint ✅ → test ❗

✅ grid-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@417a6305c3a2ae87147f2a6fb3417d06e146bd5f

✅ grid-php studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → lint ✅ → test ✅

✅ grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
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-28 21:57:03 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}

[greptile-apps]

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.

Suggested change

	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!

[pengying]

not a bad suggestion