docs: add sandbox OIDC token endpoint

[DhruvPareek]

Summary

• Add OpenAPI docs for POST /sandbox/oidc/token, including provider enum, request, response, examples, and sandbox-only errors.
• Rebuild bundled openapi.yaml and mintlify/openapi.yaml.
• Update Global Accounts sandbox docs to use the helper endpoint for OAuth credential registration and verification instead of hand-rolled JWT snippets.
• Related to this webdev PR https://app.graphite.com/github/pr/lightsparkdev/webdev/27671

Stack

• Base stack: main -> #487 -> #488.
• This PR is intentionally stacked on docs: explain realistic OIDC sandbox tokens #487 because it replaces the manual sandbox OIDC JWT example introduced there with the dedicated helper endpoint.

Test Plan

• make lint
• npx markdownlint mintlify/snippets/sandbox-global-account-magic.mdx mintlify/global-accounts/platform-tools/sandbox-testing.mdx
• 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 21, 2026 10:09pm

[github-actions]

✱ Stainless preview builds for grid

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

cli

feat(api): add create token method to sandbox oidc

csharp

feat(api): add CreateToken method to sandbox oidc

go

feat(api): add NewToken method to sandbox oidc

kotlin

feat(api): add oidc createToken endpoint to sandbox

openapi

feat(api): add createToken method to sandbox OIDC resource

php

feat(api): add createToken method to sandbox oidc

python

feat(api): add create_token method to sandbox oidc

ruby

feat(api): add create_token method to sandbox oidc resource

typescript

feat(api): add createToken method to sandbox oidc resource

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-ruby studio · code · diff

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

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

✅ grid-go studio · code · diff

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

go get github.com/stainless-sdks/grid-go@5525d4c3acbde4fce22cb382aac4752f72050c73

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

💡 Name/Renamed: 372 names were renamed due to language constraints, so fallback names will be used instead.

✅ grid-php studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → lint ✅ (prev: lint ❗) → test ✅

✅ 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-typescript 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-05-21 22:15:03 UTC

[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

• docs: add sandbox OIDC token endpoint #488 👈 (View in Graphite)
• docs: explain realistic OIDC sandbox tokens #487
• main

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

[greptile-apps]

Greptile Summary

This PR adds OpenAPI documentation for the new POST /sandbox/oidc/token endpoint (schema definitions, path definition, bundled specs) and updates the Global Accounts sandbox docs to replace the hand-rolled Node.js JWT snippet with clean curl examples that call the new helper endpoint.

• New schemas (SandboxOidcProvider, SandboxOidcTokenRequest, SandboxOidcTokenResponse) are well-formed; the 403 sandbox-only guard and the required/optional field split are correct.
• The MDX walkthrough is cleaner and easier to follow, though the credentialRegistration OpenAPI example inconsistently omits email while the MDX code snippet and credentialVerify example both include it.
• The 60-second token lifetime (visible in the response example timestamps) is not mentioned in the endpoint description; the old snippet text that explained the iat freshness requirement was removed without a replacement note.

Confidence Score: 4/5

Documentation-only change that is safe to merge; the two minor example inconsistencies do not affect API behaviour.

The schema definitions and path spec are accurate, and the new curl-based walkthrough is a clear improvement over the hand-rolled JWT. Two small gaps remain: the registration OpenAPI example omits email while the MDX snippet includes it, and the very short token lifetime (60 s, evident from the example timestamps) is no longer called out anywhere after the old freshness-requirement text was removed — a developer copy-pasting a token manually would hit a confusing 401.

openapi/paths/sandbox/sandbox_oidc_token.yaml — example consistency and missing lifetime note; mintlify/snippets/sandbox-global-account-magic.mdx — freshness-requirement context was dropped without replacement

Important Files Changed

Filename	Overview
openapi/paths/sandbox/sandbox_oidc_token.yaml	New POST /sandbox/oidc/token path definition; well-structured with appropriate sandbox-only 403, but the two request examples are inconsistent on including email
openapi/components/schemas/sandbox/SandboxOidcTokenRequest.yaml	New request schema; all fields correctly marked optional/required, constraints look correct
openapi/components/schemas/sandbox/SandboxOidcTokenResponse.yaml	New response schema; all required fields present, example timestamps are consistent with each other and with the embedded JWT payload
openapi/components/schemas/sandbox/SandboxOidcProvider.yaml	New enum schema for GOOGLE and APPLE providers; clean and minimal
mintlify/snippets/sandbox-global-account-magic.mdx	Replaces the hand-rolled Node.js JWT snippet with a clean curl-based flow using the new helper endpoint; removes the explicit claim requirements list without replacing them with a note about the 60-second token lifetime
mintlify/global-accounts/platform-tools/sandbox-testing.mdx	Minor wording updates to reference the new helper endpoint; changes are accurate and consistent
openapi/openapi.yaml	Adds the new path ref in the correct Sandbox section alongside the existing sandbox webhook test endpoint

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant SB as POST /sandbox/oidc/token
    participant Creds as POST /auth/credentials
    participant Verify as POST /auth/credentials/{id}/verify

    Note over Dev,Verify: OAuth credential registration
    Dev->>SB: provider, subject, email
    SB-->>Dev: oidcToken (60s lifetime)
    Dev->>Creds: "type=OAUTH, oidcToken"
    Creds-->>Dev: credentialId

    Note over Dev,Verify: OAuth credential verification
    Dev->>SB: provider, subject, clientPublicKey, email
    SB-->>Dev: "oidcToken with nonce=sha256(clientPublicKey)"
    Dev->>Verify: "type=OAUTH, oidcToken, clientPublicKey"
    Verify-->>Dev: session / auth result

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
openapi/paths/sandbox/sandbox_oidc_token.yaml:23-27
The `credentialRegistration` example omits `email` while the `credentialVerify` example includes it, and the MDX code snippet for registration also includes `email`. A user who copies the `credentialRegistration` example will get a Grid-derived deterministic email on the credential, then must remember not to supply an explicit email in the verify token — or must use the same deterministic value. Adding `email` to the registration example keeps the two examples symmetric and matches the MDX walkthrough.

```suggestion
          credentialRegistration:
            summary: Mint a token for OAuth credential registration
            value:
              provider: GOOGLE
              subject: alice
              email: alice@example.com
```

### Issue 2 of 2
openapi/paths/sandbox/sandbox_oidc_token.yaml:1-10
**Short token lifetime not surfaced in the endpoint description**

The response example shows `issuedAt: 2026-05-21T20:00:00Z` and `expiresAt: 2026-05-21T20:01:00Z` — a 60-second window — matching the embedded JWT's `iat`/`exp` difference. The snippet used to document the 60-second `iat` freshness requirement explicitly, but that text was removed as part of this PR. Without a note in the endpoint description, a developer who manually inspects the token (e.g., copy-pasting instead of piping through `jq`) will get a `401` on first use without an obvious cause. Adding a sentence like "The minted token is valid for 60 seconds; use it immediately." to the `description` field would close this gap.

_{Reviews (1): Last reviewed commit: "docs: add sandbox OIDC token endpoint" | Re-trigger Greptile}

[greptile-apps]

The credentialRegistration example omits email while the credentialVerify example includes it, and the MDX code snippet for registration also includes email. A user who copies the credentialRegistration example will get a Grid-derived deterministic email on the credential, then must remember not to supply an explicit email in the verify token — or must use the same deterministic value. Adding email to the registration example keeps the two examples symmetric and matches the MDX walkthrough.

Suggested change

	credentialRegistration:
	summary: Mint a token for OAuth credential registration
	value:
	provider: GOOGLE
	subject: alice
	credentialRegistration:
	summary: Mint a token for OAuth credential registration
	value:
	provider: GOOGLE
	subject: alice
	email: alice@example.com

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/sandbox/sandbox_oidc_token.yaml
Line: 23-27

Comment:
The `credentialRegistration` example omits `email` while the `credentialVerify` example includes it, and the MDX code snippet for registration also includes `email`. A user who copies the `credentialRegistration` example will get a Grid-derived deterministic email on the credential, then must remember not to supply an explicit email in the verify token — or must use the same deterministic value. Adding `email` to the registration example keeps the two examples symmetric and matches the MDX walkthrough.

```suggestion
          credentialRegistration:
            summary: Mint a token for OAuth credential registration
            value:
              provider: GOOGLE
              subject: alice
              email: alice@example.com
```

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

[greptile-apps]

Short token lifetime not surfaced in the endpoint description

The response example shows issuedAt: 2026-05-21T20:00:00Z and expiresAt: 2026-05-21T20:01:00Z — a 60-second window — matching the embedded JWT's iat/exp difference. The snippet used to document the 60-second iat freshness requirement explicitly, but that text was removed as part of this PR. Without a note in the endpoint description, a developer who manually inspects the token (e.g., copy-pasting instead of piping through jq) will get a 401 on first use without an obvious cause. Adding a sentence like "The minted token is valid for 60 seconds; use it immediately." to the description field would close this gap.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/sandbox/sandbox_oidc_token.yaml
Line: 1-10

Comment:
**Short token lifetime not surfaced in the endpoint description**

The response example shows `issuedAt: 2026-05-21T20:00:00Z` and `expiresAt: 2026-05-21T20:01:00Z` — a 60-second window — matching the embedded JWT's `iat`/`exp` difference. The snippet used to document the 60-second `iat` freshness requirement explicitly, but that text was removed as part of this PR. Without a note in the endpoint description, a developer who manually inspects the token (e.g., copy-pasting instead of piping through `jq`) will get a `401` on first use without an obvious cause. Adding a sentence like "The minted token is valid for 60 seconds; use it immediately." to the `description` field would close this gap.

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

[pengying]

is this to generate a fake oidc token?

I'm not certain that we'll need to do this? I think if an integrator is going down this path, they probably already have a OIDC token provider.