Skip to content

docs: allow multiple passkey credentials #479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DhruvPareek wants to merge 1 commit into
base: docs-auth-signed-retry-examples
Choose a base branch
from
Open

docs: allow multiple passkey credentials #479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions mintlify/snippets/global-accounts/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Every Global Account action beyond receiving funds must be authorized by a sessi
| **`OAUTH`** | Your platform already authenticates the user via OIDC (Google, Apple, your own IdP) and you want Grid to trust the same identity. |
| **`EMAIL_OTP`** | Lowest-friction option. Works on any device with email access — no biometric hardware, identity provider, or client SDK required beyond the code entry field. |

A single internal account can hold one credential of each type concurrently. Only one `PASSKEY` and one `EMAIL_OTP` per account in v1.
A single internal account can hold one `EMAIL_OTP` credential and multiple distinct `PASSKEY` credentials concurrently. `OAUTH` credentials can be added for each supported provider identity.
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 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.

Fix in Claude Code

Copy link
Copy Markdown
Contributor Author

@DhruvPareek DhruvPareek May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new sentence is true


## Registration vs. verification

Expand Down Expand Up @@ -501,7 +501,7 @@ Same pattern as the first activation: call `/challenge` to send a new OTP, then

## Managing credentials

Every Global Account starts with a single credential — the one used in the <a href="overview#quickstart">quickstart</a>. In production, encourage customers to register a second credential of a different type (e.g., an email OTP alongside a passkey) so the account is recoverable if their primary device is lost. Adding, revoking, and rotating credentials after the first all go through the same **two-step signed-retry** pattern.
Every Global Account starts with a single credential — the one used in the <a href="overview#quickstart">quickstart</a>. In production, encourage customers to register a backup credential, such as another passkey or an email OTP, so the account is recoverable if their primary device is lost. Adding, revoking, and rotating credentials after the first all go through the same **two-step signed-retry** pattern.

### List credentials

Expand Down Expand Up @@ -617,7 +617,7 @@ Requires an active session on an *existing* credential on the same account. The
</Steps>

<Note>
Only one credential of each type (`EMAIL_OTP`, `PASSKEY`) is allowed per internal account in v1. Registering a second credential of the same type returns `400 EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS` or `400 PASSKEY_CREDENTIAL_ALREADY_EXISTS`.
Only one `EMAIL_OTP` credential is allowed per internal account. Multiple distinct `PASSKEY` credentials are allowed; registering the same WebAuthn credentialId twice returns `400 PASSKEY_CREDENTIAL_ALREADY_EXISTS`.
</Note>

### Revoke a credential
Expand Down
6 changes: 3 additions & 3 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion openapi/components/schemas/errors/Error400.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ properties:
| UNSUITABLE_DOCUMENT | Document type is not accepted or not supported |
| INCOMPLETE | Document is missing pages or sides |
| EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time |
Comment thread
greptile-apps[bot] marked this conversation as resolved.
| PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential is already registered on the target internal account; only one passkey credential is supported per internal account in v1 |
| PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account |
enum:
- INVALID_INPUT
- MISSING_MANDATORY_USER_INFO
Expand Down
14 changes: 7 additions & 7 deletions openapi/paths/auth/auth_credentials.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ post:
Embedded Wallet internal accounts are initialized with an `EMAIL_OTP`
credential tied to the customer email on the account. Use this endpoint
to add another credential (`OAUTH` or `PASSKEY`), or to add `EMAIL_OTP`
back after it has been removed. Only one `EMAIL_OTP` credential and one
`PASSKEY` credential are supported per internal account.
back after it has been removed. Only one `EMAIL_OTP` credential is
supported per internal account; multiple distinct `PASSKEY` credentials
may be registered.


Adding a credential requires a signature from an existing verified
Expand Down Expand Up @@ -160,11 +161,10 @@ post:
expiresAt: '2026-04-08T15:35:00Z'
'400':
description: >-
Bad request. Returned with `EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS` or
`PASSKEY_CREDENTIAL_ALREADY_EXISTS` when registering a credential type
that already exists on the internal account. Only one email OTP
credential and one passkey credential are supported per internal
account at this time.
Bad request. Returned with `EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS`
when registering an email OTP credential while one already exists, or
`PASSKEY_CREDENTIAL_ALREADY_EXISTS` when registering a passkey whose
WebAuthn credentialId is already attached to the internal account.
content:
application/json:
schema:
Expand Down
Loading