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 19, 2026 8:38pm

[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]

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: 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

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 ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ✅)

✅ grid-go studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ❗)

go get github.com/stainless-sdks/grid-go@85ae1dbcc234e2da2389f67fd2b1c5c61ca4b085

✅ grid-kotlin studio · code · diff

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

✅ 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 ⏭️ (prev: test ✅)

✅ grid-csharp studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ❗) → lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ❗)

✅ grid-php studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → lint ⏭️ (prev: lint ✅) → test ⏭️ (prev: test ✅)

✅ grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ⏭️ (prev: build ❗) → lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: 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 ⏭️ (prev: 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-19 20:40:18 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