docs: allow multiple passkey credentials

[DhruvPareek]

Summary

• Document one EMAIL_OTP credential and multiple distinct PASSKEY credentials.
• Update duplicate passkey error docs to refer to duplicate WebAuthn credentialId.
• Update Global Accounts authentication docs to recommend passkeys as backup credentials.
• Rebuild bundled OpenAPI specs.

Test Plan

• make build
• npm run lint
• git diff --check

[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:21pm

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 19, 2026, 7:17 PM

[DhruvPareek]

• docs: explain realistic OIDC sandbox tokens #487 : 2 dependent PRs (#488 , #489 )
• docs: align auth endpoint docs with PDF #481
• docs: allow multiple passkey credentials #479 👈 (View in Graphite)
• 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(api): clarify multiple PASSKEY credentials allowed in credential creation

go

docs(api): clarify multiple passkeys supported in authcredential

kotlin

docs(api): clarify multiple passkey support in auth credentials create

openapi

docs(api): clarify multiple passkey support in auth credentials

php

docs(api): update passkey credential limit documentation in auth credentials

python

docs(api): clarify multiple passkey support in auth credentials

ruby

docs(api): clarify multiple passkey credentials supported in auth

typescript

docs(api): clarify passkey credential limits 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 a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/7f7969ad8fa1c75c834ba524b4f64ab5390067e3/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/eacb5cbe6ac9749abd625c8dd2749b8cb1168617/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@b7b40c168db50d13f32357fdb15391bd48b961fe

✅ 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 test 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-28 21:43:16 UTC

[greptile-apps]

Greptile Summary

This PR updates the authentication credential documentation to reflect that multiple distinct PASSKEY credentials (differentiated by WebAuthn credentialId) are now allowed per internal account, while the one-per-account limit for EMAIL_OTP remains. Error descriptions and user-facing guidance are updated consistently across both source and bundled OpenAPI specs.

• Credential limits clarified: PASSKEY_CREDENTIAL_ALREADY_EXISTS now correctly scopes the uniqueness constraint to the WebAuthn credentialId rather than credential type, and the endpoint description, 400 response prose, inline note, and the global-accounts MDX snippet are all updated in sync.
• Backup credential guidance updated: The "Managing credentials" section now recommends adding another passkey (or an email OTP) as a backup, which aligns with the relaxed passkey limit.
• Bundled specs regenerated: openapi.yaml and mintlify/openapi.yaml are rebuilt via make build and match the source changes exactly.

Confidence Score: 5/5

Documentation-only change with no application logic; all updated descriptions are consistent across source and bundled files.

All five changed files are documentation or generated spec bundles. The credential-limit semantics are updated consistently in the source YAML, the bundled root spec, the Mintlify bundle, and the MDX snippet. No logic, migrations, or API behaviour is altered.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/paths/auth/auth_credentials.yaml	Endpoint description updated to allow multiple distinct PASSKEY credentials; 400 response description updated to clarify per-credentialId uniqueness constraint.
openapi/components/schemas/errors/Error400.yaml	Updated PASSKEY_CREDENTIAL_ALREADY_EXISTS description to reflect WebAuthn credentialId-scoped uniqueness; EMAIL_OTP entry unchanged.
mintlify/snippets/global-accounts/authentication.mdx	Updated credential multiplicity docs: one EMAIL_OTP, multiple distinct PASSKEYs, OAUTH per provider; backup credential guidance now recommends adding a second passkey.
openapi.yaml	Bundled root spec regenerated from source; changes are identical to source files.
mintlify/openapi.yaml	Bundled Mintlify spec regenerated from source; changes are identical to source files.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[POST /auth/credentials] --> B{Credential type?}
    B --> |EMAIL_OTP| C{EMAIL_OTP already exists?}
    B --> |PASSKEY| D{Same WebAuthn credentialId already registered?}
    B --> |OAUTH| E[Add credential for provider identity]
    C --> |Yes| F[400 EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS]
    C --> |No| G[202 → signed retry → 201 Created]
    D --> |Yes| H[400 PASSKEY_CREDENTIAL_ALREADY_EXISTS]
    D --> |No| I[202 → signed retry → 201 Created - Multiple distinct PASSKEYs allowed]
    E --> J[202 → signed retry → 201 Created]

Loading

_{Reviews (4): Last reviewed commit: "docs: allow multiple passkey credentials" | Re-trigger Greptile}

[greptile-apps]

Unverified OAUTH multiplicity claim

The new sentence — "OAUTH credentials can be added for each supported provider identity" — is a behavioral assertion that isn't corroborated by any change in the API error codes or the OpenAPI spec. The old text implied one credential of each type; this PR only updates the PASSKEY constraint with a matching PASSKEY_CREDENTIAL_ALREADY_EXISTS clarification. If the OAUTH limit is also provider-scoped (i.e., one per provider rather than one total), there should be a corresponding error-code description (or at least a note in the API spec) backing this claim. Without it, a developer who tries to register a second OAUTH credential and hits an undocumented error will be confused by the mismatch between docs and API behavior.

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/global-accounts/authentication.mdx
Line: 9

Comment:
**Unverified OAUTH multiplicity claim**

The new sentence — "OAUTH credentials can be added for each supported provider identity" — is a behavioral assertion that isn't corroborated by any change in the API error codes or the OpenAPI spec. The old text implied one credential of each type; this PR only updates the PASSKEY constraint with a matching `PASSKEY_CREDENTIAL_ALREADY_EXISTS` clarification. If the OAUTH limit is also provider-scoped (i.e., one per provider rather than one total), there should be a corresponding error-code description (or at least a note in the API spec) backing this claim. Without it, a developer who tries to register a second OAUTH credential and hits an undocumented error will be confused by the mismatch between docs and API behavior.

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

[DhruvPareek]

The new sentence is true

[restamp-bot]

573b869 is a pure rebase onto 36bc92e. Approving based on @pengying's previous approval of bd061b8.

[restamp-bot]

573b869 is a pure rebase onto 36bc92e. Approving based on @pengying's previous approval of bd061b8.

The base branch was changed.