[grid-api] Deprecate encryptedSessionSigningKey + accept compressed clientPublicKey for client-held sessions (SP-3690)

[carsonp6]

Syncs the canonical spec with webdev #32460 (SP-3690 Part 1 — deprecate; keep functional). Part 2 (field removal) is the gated future follow-on.

Consolidates #811 — the clientPublicKey encoding now actively selects the flow, rather than the deprecation being announced with no way for a client to opt in.

What changed

Deprecate encryptedSessionSigningKey

• AuthSession.encryptedSessionSigningKey marked deprecated: true, with description reframed around the client-held-key model.
• Matching description updates across createAuthCredential, verifyAuthCredential, challengeAuthCredential, refreshAuthSession path descriptions, plus AuthCredentialChallengeRequest, AuthSessionRefreshRequest, and OauthCredentialVerifyRequestFields schemas.
• Removed a stale encryptedSessionSigningKey from the EMAIL_OTP refresh example (EMAIL_OTP sessions never populate this field).

Accept compressed keys to select the client-held-key flow (non-breaking)

• clientPublicKey encoding is now the flow selector: compressed SEC1 (02/03 prefix, 66 hex) opts into the client-held session key model already used by EMAIL_OTP/SMS_OTP, now extended to OAUTH and PASSKEY; uncompressed SEC1 (04 prefix, 130 hex) keeps the deprecated legacy HPKE-sealed flow.
• AuthCredentialChallengeRequest.yaml and AuthSessionRefreshRequest.yaml clientPublicKey pattern relaxed from ^04[0-9a-fA-F]{128}$ to ^(0[23][0-9a-fA-F]{64}|04[0-9a-fA-F]{128})$ (challenge minLength 130 → 66). OauthCredentialVerifyRequestFields.yaml had no pattern and already accepted both.
• Representative clientPublicKey examples switched to the compressed encoding.
• New "Client-held session key" section in mintlify/snippets/global-accounts/client-keys.mdx describing the recommended flow, mirroring the existing OTP client-held statement.
• scripts/embedded-wallet-sign.js: gen-keypair takes a --compressed flag to generate a client-held session key for the OAuth/PASSKEY path.

Rebundled openapi.yaml / mintlify/openapi.yaml via make build.

Test plan

• make build regenerates the bundle cleanly from the modular openapi/ source
• make lint — 0 errors, same warning/info baseline as main
• oasdiff breaking main openapi.yaml --fail-on ERR — 0 errors (2 request-property-pattern-changed warnings for the relaxed patterns; a relaxation is a superset, so not a breaking change)
• node scripts/embedded-wallet-sign.js gen-keypair --compressed — verified output is 66 hex chars with a 02/03 prefix matching the relaxed pattern; default (no flag) unchanged at 130 hex chars with 04 prefix

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 12, 2026, 9:05 PM

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Aug 13, 2026 5:09pm
grid-wallet-demo	Ignored	Preview	Aug 13, 2026 5:09pm

[github-actions]

✱ Stainless preview builds for grid

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

cli

docs(api): clarify client-public-key usage in auth credentials and sessions

go

docs(api): document client-held-key model in auth credential and session methods

kotlin

fix(types): deprecate encryptedSessionSigningKey in AuthSession

openapi

fix(types): deprecate encryptedSessionSigningKey in AuthSession

php

docs(api): deprecate encryptedSessionSigningKey, document client-held-key model

python

docs(api): clarify session key handling in auth credentials and sessions

ruby

docs(api): update auth credential and session documentation for client-held-key model

typescript

docs(api): update auth session key documentation for client-held-key model

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

✅ grid-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/71b6851ea4b832befdc8949e8189c3a2142e4b52/dist.tar.gz

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ❗ → lint ❗ → test ❗

✅ grid-ruby studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ grid-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@d52e5831bb6f1c126b530c7065a20b3f7e05c894

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ 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/5ec27b27cc7d94d4ef273618b09d3232144af713/grid-0.0.1-py3-none-any.whl

✅ grid-php studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ grid-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ grid-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ❗

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

---

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-08-13 17:14:25 UTC

[greptile-apps]

Greptile Summary

The PR deprecates AuthSession.encryptedSessionSigningKey, documents the client-held session-key model across authentication and refresh operations, removes the obsolete EMAIL_OTP example field, and regenerates both bundled specifications.

• Adds OpenAPI deprecation metadata without removing or making the field required.
• Reframes OAuth, passkey, and refresh key handling around client-generated private keys.
• Leaves related integration guides and signing tooling describing the incompatible encrypted-key flow.

Confidence Score: 4/5

This PR should not merge until the related authentication guides and signing helper are aligned with the newly canonical client-held-key flow.

The OpenAPI reference now tells OAuth, passkey, and refresh clients to retain their generated private key, while repository integration instructions still require decrypting response key material that migrated sessions omit.

Files Needing Attention: openapi/components/schemas/auth/AuthSession.yaml, openapi/paths/auth/auth_credentials_{id}verify.yaml, openapi/paths/auth/auth_sessions{id}_refresh.yaml

Important Files Changed

Filename	Overview
openapi/components/schemas/auth/AuthSession.yaml	Deprecates the optional encrypted key and establishes client-held keys as canonical, but now conflicts with existing integration guides.
openapi/paths/auth/auth_credentials_{id}_verify.yaml	Updates verification semantics consistently with AuthSession, while unchanged guides still instruct OAuth and passkey clients to decrypt response key material.
openapi/paths/auth/auth_sessions_{id}_refresh.yaml	Documents client-held refresh keys and removes the EMAIL_OTP example field, but the session-management guide still prescribes decrypting a returned key.
openapi.yaml	Generated bundle accurately reflects the modular source changes.
mintlify/openapi.yaml	Generated Mintlify bundle remains synchronized with the root bundle.

Prompt To Fix All With AI

### Issue 1
openapi/components/schemas/auth/AuthSession.yaml:7-11
**Conflicting session-key instructions**

When an integrator follows the existing OAuth, passkey, or refresh guides, those guides require decrypting `encryptedSessionSigningKey`, while this changed contract says migrated sessions omit that field and use the private key generated before authentication, causing integrations to fail before they can make subsequent signed requests. Update the associated Mintlify guides and signing helper alongside this contract.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Deprecate AuthSession.encryptedSessionSi..." | Re-trigger Greptile}

[greptile-apps]

Conflicting session-key instructions

When an integrator follows the existing OAuth, passkey, or refresh guides, those guides require decrypting encryptedSessionSigningKey, while this changed contract says migrated sessions omit that field and use the private key generated before authentication, causing integrations to fail before they can make subsequent signed requests. Update the associated Mintlify guides and signing helper alongside this contract.

Knowledge Base Used: Auth and SCA

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/auth/AuthSession.yaml
Line: 7-11

Comment:
**Conflicting session-key instructions**

When an integrator follows the existing OAuth, passkey, or refresh guides, those guides require decrypting `encryptedSessionSigningKey`, while this changed contract says migrated sessions omit that field and use the private key generated before authentication, causing integrations to fail before they can make subsequent signed requests. Update the associated Mintlify guides and signing helper alongside this contract.

**Knowledge Base Used:** [Auth and SCA](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/auth-and-sca.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[carsonp6]

Declining this one for this PR. The gap is real (the Mintlify narrative guides and the embedded-wallet-sign.js decrypt-bundle helper still describe OAuth/PASSKEY as always decrypting encryptedSessionSigningKey, with no mention of the client-held-key model), but #817 is intentionally scoped to the OpenAPI reference only — it's Part 1 of SP-3690, syncing wording 1:1 from webdev's grid-api spec change, with field removal deferred to a gated Part 2.

The integration-guide side of this is already in flight in a separate PR (#811, "docs(auth): document client-held session key as the primary Embedded Wallet flow"), which reframes client-keys.mdx around the client-held-key model as primary. We keep spec/reference changes and narrative-guide rewrites in separate PRs rather than bundling them, so we won't fold the guide/helper updates into this one — they'll land via #811 (guides) and a follow-up for the dev-tool script.