Add OTP email update endpoint to OpenAPI

[DhruvPareek]

Summary:

• Moves the email OTP update OpenAPI path from PATCH /internal-accounts/{id}/email to PATCH /auth/credentials/{id}, matching auth credential ownership.
• Models credential update as the existing two-step signed-retry flow: initial calls return AuthSignedRequestChallenge with payloadToSign, requestId, expiresAt, and credential type; signed retries return 200 with the updated AuthMethod.
• Adds AuthCredentialUpdateRequest as a partial credential patch body. Today it supports email for EMAIL_OTP credentials only.
• Keeps EMAIL_OTP_EMAIL_ALREADY_EXISTS on Error409 for duplicate EMAIL_OTP email addresses.
• Wires the new auth credential update operation into Stainless and regenerates openapi.yaml plus mintlify/openapi.yaml.

Files added:

• openapi/components/schemas/auth/AuthCredentialUpdateRequest.yaml

Files updated:

• .stainless/stainless.yml
• openapi/paths/auth/auth_credentials_{id}.yaml
• openapi/components/schemas/auth/AuthSignedRequestChallenge.yaml
• openapi/components/schemas/errors/Error409.yaml

Files removed:

• openapi/paths/internal_accounts/internal_accounts_{id}_email.yaml
• openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateRequest.yaml
• openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateResponse.yaml

Testing:

• npm run lint:openapi
• 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 11, 2026 10:56pm

[DhruvPareek]

• Align signed request id examples #453
• Add wallet privacy endpoint to OpenAPI #452
• Add auth session refresh endpoints #451
• Add OTP email update endpoint to OpenAPI #450 👈 (View in Graphite)
• Add passkey credentialId to auth challenge response #449
• Add passkey credentialId to auth credential list #448
• Align auth session request-id contract #445 : 1 other dependent PR (#446 )
• Align auth credential create contract #444
• 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 updateEmail method to customers

openapi

feat(api): add update_email method to internal_accounts

python

feat(api): add update_email method to customers

typescript

feat(api): add updateEmail method to customers

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

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

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

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

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

✅ grid-openapi studio · code · diff

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

---

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-08 00:28:29 UTC

[greptile-apps]

Greptile Summary

This PR documents a new PATCH /internal-accounts/{id}/email endpoint for updating the EMAIL_OTP credential email on an Embedded Wallet account, following the existing two-step signed-retry pattern established by the export endpoint.

• Adds the path definition, InternalAccountEmailUpdateRequest and InternalAccountEmailUpdateResponse schemas, and wires them into the root spec and both generated bundles.
• Extends Error409 with the EMAIL_OTP_EMAIL_ALREADY_EXISTS error code and documents the 409 conflict response on the new endpoint.

Confidence Score: 5/5

Safe to merge — this is a documentation-only change that correctly mirrors the established signed-retry flow pattern with no logic or runtime code affected.

The new endpoint definition closely tracks the sibling export endpoint, all required response codes (including the previously requested 409) are present, the schema fields are correctly typed, and the bundled outputs match the source. The only finding is a cosmetic response-ordering inconsistency in the source YAML that the bundler already corrects in generated output.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/paths/internal_accounts/internal_accounts_{id}_email.yaml	New PATCH endpoint for updating EMAIL_OTP email via the two-step signed-retry flow; closely mirrors the export endpoint pattern with correct responses (200, 202, 400, 401, 409, 404, 500), though 409 and 404 are listed out of ascending order in the source file.
openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateRequest.yaml	New request schema with required email field (format: email), detailed description, and correct structure.
openapi/components/schemas/internal_accounts/InternalAccountEmailUpdateResponse.yaml	New response schema with required id, email, and updatedAt fields; missing top-level description (noted in previous thread).
openapi/components/schemas/errors/Error409.yaml	Adds EMAIL_OTP_EMAIL_ALREADY_EXISTS to the Error409 error code enum and description table.
openapi/openapi.yaml	Wires /internal-accounts/{id}/email path ref into the root spec alongside the existing export path.
openapi.yaml	Auto-generated bundle; correctly includes the new endpoint inline with all schema definitions.
mintlify/openapi.yaml	Auto-generated Mintlify bundle; identical new content to openapi.yaml; bundler correctly reorders 404 before 409 in the output.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Grid API

    C->>G: "PATCH /internal-accounts/{id}/email<br/>Body: { email }"
    G-->>C: "202 Accepted<br/>{ payloadToSign, requestId, expiresAt }"

    Note over C: Sign payloadToSign with session API keypair

    C->>G: "PATCH /internal-accounts/{id}/email<br/>Grid-Wallet-Signature: stamp<br/>Request-Id: requestId<br/>Body: { email }"
    alt Email available
        G-->>C: "200 OK { id, email, updatedAt }"
    else Email already in use
        G-->>C: 409 Conflict EMAIL_OTP_EMAIL_ALREADY_EXISTS
    else Signature or challenge mismatch
        G-->>C: 401 Unauthorized
    end

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
openapi/paths/internal_accounts/internal_accounts_{id}_email.yaml:103-118
The `409` response block is placed before `404`, breaking the ascending HTTP status-code order that every other endpoint in this repo follows (including the sibling export endpoint). OpenAPI parsers are order-agnostic so this is harmless at runtime, but the bundled output already reorders them correctly, which signals the mismatch with the source.

```suggestion
    '404':
      description: Internal account not found
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error404.yaml
    '409':
      description: >-
        Conflict. Returned when the supplied email address is already
        associated with an `EMAIL_OTP` credential on this or another
        internal account.
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/errors/Error409.yaml
    '500':
```

_{Reviews (2): Last reviewed commit: "Add internal account email update endpoi..." | Re-trigger Greptile}

[github-actions]

✱ Stainless preview builds for grid

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

kotlin

feat(api): add updateEmail method to customers

openapi

feat(api): add update_email method to internal_accounts

python

feat(api): add update_email method to customers

typescript

feat(api): add updateEmail method to customers

⚠️ grid-python studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

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

⚠️ grid-kotlin studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

⚠️ grid-openapi studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗

⚠️ grid-typescript 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 ❗

---

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-11 23:13:30 UTC

[pengying]

I thought we weren't going to do the /internal_account/{id}/credential patch?

Also I thought the flow would be to add a second email otp address then delete the first one? Do we need a patch?

[DhruvPareek]

PPatch is realy easy to impplement because the delete endpoint just calls turnkey and modifies the email field to "". We can pretty easily add this patch endpoint and just modify the email address directly instead of requiring two calls

[pengying]

If you guys wanna support patch, make it a PATCH on the /auth/credential/{id}

[DhruvPareek]

updated it to PATCH on the /auth/credential/{id}