Update auth credential /challenge body

[carsonp6]

TL;DR

The POST /auth/credentials/{id}/challenge endpoint now accepts a request body containing a clientPublicKey for passkey credential re-challenges.

What changed?

The challengeAuthCredential endpoint now accepts an optional JSON request body with a clientPublicKey field. For PASSKEY credentials, this field is required and must be a client-generated P-256 public key in hex-encoded uncompressed SEC1 format (130 hex characters, 04-prefixed). Grid bakes this key into the Turnkey session-creation payload that the returned challenge is computed from, sealing the resulting session signing key to the client.

The field is ignored for EMAIL_OTP and OAUTH credentials, where the credential type alone is sufficient to issue a challenge. Two request body examples are documented: one for passkey re-challenges (with clientPublicKey) and one for email-OTP or OAuth re-challenges (empty body).

How to test?

• Issue a POST /auth/credentials/{id}/challenge for a PASSKEY credential with a valid clientPublicKey in the request body and confirm a PasskeyAuthChallenge is returned.
• Issue the same request without a clientPublicKey for a PASSKEY credential and confirm an appropriate error is returned.
• Issue a POST /auth/credentials/{id}/challenge for an EMAIL_OTP or OAUTH credential with an empty body and confirm the challenge is issued successfully.

Why make this change?

Previously, the challenge endpoint had no way to bind the resulting Turnkey session to a specific client. By requiring the client to supply its ephemeral public key upfront, Grid can embed it into the session-creation payload before computing the challenge, ensuring the session signing key is cryptographically sealed to the client that initiated the challenge.

[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 28, 2026 3:46am

[carsonp6]

• Update auth credential /challenge body #407 👈 (View in Graphite)
• main

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

[greptile-apps]

Greptile Summary

This PR updates the POST /auth/credentials/{id}/challenge endpoint to accept an optional JSON request body containing a clientPublicKey field, which is required for PASSKEY credentials so Grid can bind the resulting Turnkey session signing key to the specific client. The previous reviewer's concern about missing schema constraints (pattern, minLength, maxLength) has been addressed in the new AuthCredentialChallengeRequest schema.

Confidence Score: 5/5

Safe to merge — purely OpenAPI spec documentation changes with no implementation code, and the schema constraints are correctly applied.

No P0 or P1 findings. The only pre-existing P2 concern (OAUTH credential response behaviour undocumented) was already flagged in a previous review. The schema pattern, length constraints, and example values are all correct.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/components/schemas/auth/AuthCredentialChallengeRequest.yaml	New schema for the challenge request body; includes correct pattern, minLength, and maxLength constraints on clientPublicKey. No required array, which is appropriate since the field is only conditionally required at the server level.
openapi/paths/auth/auth_credentials_{id}_challenge.yaml	Adds requestBody (required: false) referencing the new schema, with two examples (passkey and emailOtpOrOauth). Updated PASSKEY description to mention the clientPublicKey requirement. OAUTH credential response behaviour remains undocumented in the endpoint description (pre-existing concern).
openapi.yaml	Bundled spec — mirrors the modular YAML changes: adds requestBody, new AuthCredentialChallengeRequest component schema, and updated PASSKEY description.
mintlify/openapi.yaml	Mintlify-targeted bundled spec — identical changes to openapi.yaml; no issues.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant G as Grid API
    participant T as Turnkey

    Note over C,T: PASSKEY re-challenge flow (new)
    C->>C: Generate ephemeral P-256 key pair
    C->>G: POST /auth/credentials/{id}/challenge
    Note right of C: { clientPublicKey: "04..." }
    G->>G: Validate clientPublicKey format
    Note right of G: 04-prefix, 130 hex chars
    G->>T: Create session payload baking in clientPublicKey
    T-->>G: PasskeyAuthChallenge (challenge, requestId, expiresAt)
    G-->>C: 200 PasskeyAuthChallenge
    C->>C: navigator.credentials.get(challenge)
    C->>G: POST /auth/credentials/{id}/verify
    Note right of C: Request-Id: requestId

    Note over C,G: EMAIL_OTP / OAUTH re-challenge flow (unchanged)
    C->>G: POST /auth/credentials/{id}/challenge
    Note right of C: {} (empty body)
    G-->>C: 200 AuthMethod (OTP sent out-of-band)

Loading

_{Reviews (2): Last reviewed commit: "Address review feedback: extract challen..." | Re-trigger Greptile}

[carsonp6]

@greptileai

[github-actions]

✱ Stainless preview builds

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

kotlin

feat(api): add clientPublicKey parameter to credential resendChallenge method

openapi

feat(api): add clientPublicKey parameter to auth credentials challenge

python

feat(api): add client_public_key parameter to credentials resend_challenge

typescript

feat(api): add clientPublicKey param to auth credentials resendChallenge

✅ grid-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ grid-python studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-kotlin studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-typescript studio · code

Your SDK build had at least one "note" diagnostic.
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-28 04:54:37 UTC