Align auth session request-id contract

[DhruvPareek]

• Fix some description to be more accurate for new API endpoints. POST /auth/credentials no longer emis a 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	May 7, 2026 11:44pm

[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

• Align auth session request-id contract #445 : 2 dependent PRs (#446 , #448 ) 👈 (View in Graphite)
• 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

docs(api): update credential verification and session signing key documentation

openapi

docs(api): update requestId examples and auth credential documentation

python

chore(internal): update auth credentials documentation and test fixtures

typescript

chore(tests): update Request-Id header format in auth test fixtures

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 ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/grid-python/47e98a0983e37a988ce5f2f92c53f889b27bda10/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 ✅ → 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 ✅

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

✅ 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-07 23:47:55 UTC

[greptile-apps]

Greptile Summary

This PR narrows the PASSKEY credential description in the POST /auth/credentials/{id}/verify endpoint: it removes POST /auth/credentials as a challenge source (keeping only POST /auth/credentials/{id}/challenge), drops the explicit mention of clientPublicKey from the verify call, and clarifies that clientPublicKey is now bound at the challenge step.

• The endpoint-level description is updated consistently across the source YAML and both generated bundles (openapi.yaml, mintlify/openapi.yaml).
• The Request-Id header parameter description in the source file still mentions POST /auth/credentials as a valid challenge origin, directly contradicting the updated endpoint prose — this should be updated to match.

Confidence Score: 3/5

The endpoint prose and the Request-Id parameter description now contradict each other about which endpoint produces the challenge requestId, which could lead callers to echo an invalid requestId and receive a 401.

The Request-Id header parameter description in auth_credentials_{id}_verify.yaml still lists POST /auth/credentials as a valid challenge origin after the endpoint description was updated to remove it — callers relying on the parameter-level docs will have an incorrect mental model of the PASSKEY flow.

openapi/paths/auth/auth_credentials_{id}_verify.yaml — the Request-Id parameter description needs updating to match the new endpoint prose; both generated bundles will then need to be rebuilt via make build.

Important Files Changed

Filename	Overview
openapi/paths/auth/auth_credentials_{id}_verify.yaml	Endpoint description updated to remove POST /auth/credentials as a PASSKEY challenge source and clarify clientPublicKey is bound at the challenge step, but the Request-Id header parameter description still references the old dual-source wording, leaving an internal contradiction.
openapi.yaml	Generated bundle updated via make build to reflect the source YAML change; carries the same inconsistency between the endpoint description and the Request-Id parameter description.
mintlify/openapi.yaml	Mintlify bundle updated identically to openapi.yaml; same inconsistency applies.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Grid

    Note over Client,Grid: PASSKEY auth flow (after this PR)
    Client->>Grid: "POST /auth/credentials/{id}/challenge (clientPublicKey bound here)"
    Grid-->>Client: "{ challenge, requestId }"

    Client->>Client: navigator.credentials.get(challenge)
    Client->>Grid: "POST /auth/credentials/{id}/verify Request-Id: {requestId} body: { type: PASSKEY, assertion }"
    Grid-->>Client: "{ encryptedSessionSigningKey, expiresAt }"

    Note over Client,Grid: EMAIL_OTP / OAUTH flow (unchanged)
    Client->>Grid: "POST /auth/credentials/{id}/verify body: { type, otp/oidcToken, clientPublicKey }"
    Grid-->>Client: "{ encryptedSessionSigningKey, expiresAt }"

Loading

Comments Outside Diff (1)

1. openapi/paths/auth/auth_credentials_{id}_verify.yaml, line 45-49 (link)

   Request-Id parameter description contradicts updated endpoint description

   The Request-Id header parameter description (lines 45–48) still says the requestId can come from POST /auth/credentials OR POST /auth/credentials/{id}/challenge, but the updated endpoint description now only lists POST /auth/credentials/{id}/challenge as the challenge source for PASSKEY credentials. A developer reading both sections will get contradictory signals about which endpoints can produce a valid requestId to echo here.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: openapi/paths/auth/auth_credentials_{id}_verify.yaml
   Line: 45-49
   
   Comment:
   **`Request-Id` parameter description contradicts updated endpoint description**
   
   The `Request-Id` header parameter description (lines 45–48) still says the `requestId` can come from `POST /auth/credentials` OR `POST /auth/credentials/{id}/challenge`, but the updated endpoint description now only lists `POST /auth/credentials/{id}/challenge` as the challenge source for `PASSKEY` credentials. A developer reading both sections will get contradictory signals about which endpoints can produce a valid `requestId` to echo here.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

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/auth/auth_credentials_{id}_verify.yaml:45-49
**`Request-Id` parameter description contradicts updated endpoint description**

The `Request-Id` header parameter description (lines 45–48) still says the `requestId` can come from `POST /auth/credentials` OR `POST /auth/credentials/{id}/challenge`, but the updated endpoint description now only lists `POST /auth/credentials/{id}/challenge` as the challenge source for `PASSKEY` credentials. A developer reading both sections will get contradictory signals about which endpoints can produce a valid `requestId` to echo here.

```suggestion
      description: >-
        The `requestId` returned alongside the Grid-issued `challenge` from
        `POST /auth/credentials/{id}/challenge`, echoed back here so Grid
        can correlate the assertion with the pending challenge. Required
        when `type` is `PASSKEY`; ignored for `EMAIL_OTP` and `OAUTH`.
```

_{Reviews (1): Last reviewed commit: "Align auth session request-id contract" | Re-trigger Greptile}