add Embedded Wallet Auth endpoint for Email OTP challenge

[DhruvPareek]

Endpoint

• POST /auth/credentials/{id}/challenge — re-issue the challenge for an existing credential without rebuilding it. For EMAIL_OTP, triggers a new OTP email so the user can call /verify again after a missed or expired code.

Request / response

POST /auth/credentials/{id}/challenge
(no body)

→ 200 AuthMethod   // { id, accountId, type, nickname, createdAt, updatedAt }

Resources

No new schemas. Reuses AuthMethod from the parent PR (#349). Stainless config adds challenge to the auth.credentials resource methods.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	Apr 22, 2026 1:54am

[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

• add Embedded Wallet OAUTH credential to additional credential flow #362
• add Embedded Wallet OAUTH credential verify #361
• add Embedded Wallet OAUTH credential create #360
• modify /quotes and /quote/{quoteId}/execute for Embedded Wallet transfers #356
• add Embedded Wallet Auth endpoint for Email OTP challenge #350 👈 (View in Graphite)
• add Embedded Wallet Auth endpoints for Email OTP create + verify #349
• main

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

[github-actions]

✱ Stainless preview builds

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

kotlin

feat(api): add resendChallenge method to credentials

openapi

feat(api): add resend challenge method to auth credentials

python

feat(api): add resend_challenge method to auth.credentials

typescript

feat(api): add resendChallenge method to 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-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/8a2f6d37a5cc6a869790f63fa47afa2258b63e5c/grid-0.0.1-py3-none-any.whl

✅ 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/61f2fe7614400ad97caa4c3784ad4d3536cfbda0/dist.tar.gz

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

---

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-04-22 01:59:36 UTC

[greptile-apps]

Greptile Summary

This PR adds POST /auth/credentials/{id}/challenge — a single new endpoint that re-issues the challenge for an existing credential (triggering a new OTP email for EMAIL_OTP types) so users can call /verify again after a missed or expired code. The Stainless config, both OpenAPI bundles, and the source path file are all updated consistently.

• The id path parameter is described as "The id of the internal account" but {id} is the credential ID (AuthMethod:…), not the internal account ID (InternalAccount:…) — developers following the description would pass the wrong value and receive a 404.

Confidence Score: 4/5

Safe to merge after correcting the path parameter description — the wrong entity name would mislead API consumers into passing an internal account ID instead of a credential ID.

One P1 doc bug: the id path param description says "internal account" when it must be the AuthMethod/credential ID. This would cause 404s for developers who follow the description literally. The P2 findings (undocumented non-OTP behavior, missing 429) are non-blocking.

openapi/paths/auth/auth_credentials_{id}_challenge.yaml — path parameter description on line 19

Important Files Changed

Filename	Overview
openapi/paths/auth/auth_credentials_{id}_challenge.yaml	New endpoint spec for POST /auth/credentials/{id}/challenge; path parameter description incorrectly names the entity as "internal account" when {id} is the credential (AuthMethod) ID
.stainless/stainless.yml	Adds challenge: post /auth/credentials/{id}/challenge to the auth.credentials resource methods — straightforward and correct
openapi/openapi.yaml	Adds the /auth/credentials/{id}/challenge path $ref to the root OpenAPI index — correct
openapi.yaml	Generated bundle — includes the challengeAuthCredential operation inlined; inherits the path param description issue from the source file
mintlify/openapi.yaml	Generated bundle for Mintlify docs — mirrors openapi.yaml; no independent issues

Sequence Diagram

sequenceDiagram
    participant Client
    participant GridAPI
    participant EmailService

    Client->>GridAPI: POST /auth/credentials (EMAIL_OTP)
    GridAPI-->>Client: 201 AuthMethod {id: "AuthMethod:abc…"}
    GridAPI->>EmailService: Send OTP email

    Note over Client: OTP missed or expired

    Client->>GridAPI: POST /auth/credentials/{id}/challenge
    GridAPI-->>Client: 200 AuthMethod
    GridAPI->>EmailService: Re-send OTP email

    Client->>GridAPI: POST /auth/credentials/{id}/verify {otp, clientPublicKey}
    GridAPI-->>Client: 200 AuthSession {encryptedSessionSigningKey}

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: openapi/paths/auth/auth_credentials_{id}_challenge.yaml
Line: 19

Comment:
**Path parameter description identifies the wrong entity**

The `id` path parameter description says "The id of the internal account" but `{id}` in `/auth/credentials/{id}/challenge` is the **credential ID** (`AuthMethod.id`, e.g. `AuthMethod:019542f5-…`), not the internal account ID (`InternalAccount:…`). These carry different type prefixes; a developer reading this description would likely pass the wrong ID and get a 404. The verify endpoint has the same mismatch (inherited from the parent PR), so the error is consistent across both, but still wrong.

```suggestion
      description: The id of the authentication credential to re-challenge.
```

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

---

This is a comment left during a code review.
Path: openapi/paths/auth/auth_credentials_{id}_challenge.yaml
Line: 3-11

Comment:
**Behavior for non-EMAIL_OTP credential types is undocumented**

The description only covers `EMAIL_OTP` credentials. It does not clarify what happens when this endpoint is called for other registered credential types (passkey, OAuth). If non-OTP types return a `400`, callers benefit from knowing this upfront — especially since the endpoint is on a generic `/auth/credentials/{id}` resource that encompasses all credential types.

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

---

This is a comment left during a code review.
Path: openapi/paths/auth/auth_credentials_{id}_challenge.yaml
Line: 23-53

Comment:
**Missing `429 Too Many Requests` response for OTP rate limiting**

This endpoint triggers a new OTP email on every call. If the backend rate-limits resend requests (which is standard practice to prevent email flooding / OTP abuse), a `429` response should be documented so clients can handle backoff gracefully. Consider adding it alongside the existing `400`/`401`/`404`/`500` responses.

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

_{Reviews (1): Last reviewed commit: "feat: add POST /auth/credentials/{id}/ch..." | Re-trigger Greptile}

[greptile-apps]

Missing 429 Too Many Requests response for OTP rate limiting

This endpoint triggers a new OTP email on every call. If the backend rate-limits resend requests (which is standard practice to prevent email flooding / OTP abuse), a 429 response should be documented so clients can handle backoff gracefully. Consider adding it alongside the existing 400/401/404/500 responses.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/auth/auth_credentials_{id}_challenge.yaml
Line: 23-53

Comment:
**Missing `429 Too Many Requests` response for OTP rate limiting**

This endpoint triggers a new OTP email on every call. If the backend rate-limits resend requests (which is standard practice to prevent email flooding / OTP abuse), a `429` response should be documented so clients can handle backoff gracefully. Consider adding it alongside the existing `400`/`401`/`404`/`500` responses.

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

[pengying]

reasonable

[DhruvPareek]

added this