add DelegatedKey schemas

[DhruvPareek]

What

Adds the component schemas for the upcoming delegated signing key endpoints (/auth/delegated-keys, next PR up the stack):

Schema	Purpose
DelegatedKeyCreateRequest	accountId + nickname — Grid generates and custodies the keypair server-side
DelegatedKey	The resource: id, account, public key (informational metadata), nickname, status, timestamps
DelegatedKeyStatus	PENDING (no policy yet — cannot sign) / ACTIVE / REVOKED
DelegatedKeyListResponse	List wrapper
DelegatedKeyChallengeStep	CREATE_USER / CREATE_POLICY / DELETE_USER / DELETE_POLICY
DelegatedKeySignedRequestChallenge	SignedRequestChallenge base + step discriminating which signer activity the stamp authorizes

Why

Grid needs delegated signing authority over an embedded wallet so it can act when the user requests a payment (recurring payments, automated settlement). Delegation registers a Grid-generated P-256 API key as a non-root signer user on the wallet's sub-organization with a policy granting signing authority — every step authorized by the wallet owner via the existing signed-retry stamp pattern. The private key is custodied by Grid and never returned to the platform.

Notes for reviewers

• Schemas only — not referenced by any path yet, so the generated bundle (openapi.yaml) is unchanged in this PR. Endpoints + bundle regen land upstack.
• make lint passes with no new findings.

🤖 Generated with Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jun 11, 2026 11:48pm

[DhruvPareek]

• add /auth/delegated-keys endpoints #574
• add DelegatedKey schemas #573 👈 (View in Graphite)
• main

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

[greptile-apps]

Greptile Summary

Adds six new OpenAPI component schemas for the upcoming delegated signing key endpoints (/auth/delegated-keys). The schemas cover the create request, the resource object, status enum, challenge step enum, signed-request challenge, and list response.

• DelegatedKeyCreateRequest is missing the publicKey field that the PR description's own table lists as required; DelegatedKey.yaml's description ("generated and custodied by Grid") directly contradicts the PR's "platform-held P-256 API key" framing — one must be updated before the endpoint implementation lands upstack.
• DelegatedKeySignedRequestChallenge correctly composes SignedRequestChallenge via allOf and adds the step discriminator; DelegatedKeyStatus and DelegatedKeyChallengeStep follow existing repo enum conventions.

Confidence Score: 4/5

The create request schema is incomplete or its description is wrong — resolving the publicKey discrepancy before the endpoint implementation lands upstack is necessary to avoid a schema/implementation mismatch.

The create request schema omits the publicKey field that the PR description explicitly calls out as required, while DelegatedKey.yaml describes the key as Grid-generated — an unresolved contradiction that must be settled before the endpoint goes live.

DelegatedKeyCreateRequest.yaml and DelegatedKey.yaml need alignment on whether the platform or Grid generates the keypair, and the create request updated accordingly.

Important Files Changed

Filename	Overview
openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml	Missing publicKey property: the PR description lists it as required but neither required nor properties includes it; DelegatedKey.yaml's description contradicts the PR's "platform-held key" framing.
openapi/components/schemas/auth/DelegatedKey.yaml	Well-structured response schema; description "generated and custodied by Grid" is inconsistent with the PR's "platform-held" framing — needs alignment with whichever model is correct.
openapi/components/schemas/auth/DelegatedKeyStatus.yaml	Clean enum with bullet-list style descriptions for each status value; matches repo conventions.
openapi/components/schemas/auth/DelegatedKeyChallengeStep.yaml	Four-value enum (CREATE_USER, CREATE_POLICY, DELETE_USER, DELETE_POLICY) with clear descriptions tying each step to its endpoint; no issues.
openapi/components/schemas/auth/DelegatedKeySignedRequestChallenge.yaml	Correct allOf composition with SignedRequestChallenge; step discriminator wired to DelegatedKeyChallengeStep with proper required declaration.
openapi/components/schemas/auth/DelegatedKeyListResponse.yaml	Simple list wrapper consistent with AuthCredentialListResponse and other auth list schemas in the repo; no pagination needed at this resource cardinality.

Sequence Diagram

sequenceDiagram
    participant Platform
    participant Grid API

    Note over Platform,Grid API: Create Delegated Key (POST /auth/delegated-keys)
    Platform->>Grid API: DelegatedKeyCreateRequest (accountId, nickname[, publicKey?])
    Grid API-->>Platform: 202 DelegatedKeySignedRequestChallenge (payloadToSign, requestId, expiresAt, step=CREATE_USER)
    Platform->>Grid API: Retry with Grid-Wallet-Signature + Request-Id
    Grid API-->>Platform: 202 DelegatedKeySignedRequestChallenge (step=CREATE_POLICY)
    Platform->>Grid API: Retry with Grid-Wallet-Signature + Request-Id
    Grid API-->>Platform: 200 DelegatedKey (id, accountId, publicKey, nickname, status=ACTIVE)

    Note over Platform,Grid API: Revoke Delegated Key (DELETE /auth/delegated-keys/{id})
    Platform->>Grid API: DELETE request
    Grid API-->>Platform: 202 DelegatedKeySignedRequestChallenge (step=DELETE_USER)
    Platform->>Grid API: Retry with Grid-Wallet-Signature + Request-Id
    Grid API-->>Platform: 202 DelegatedKeySignedRequestChallenge (step=DELETE_POLICY)
    Platform->>Grid API: Retry with Grid-Wallet-Signature + Request-Id
    Grid API-->>Platform: 200 DelegatedKey (status=REVOKED)

Loading

_{Reviews (4): Last reviewed commit: "feat(openapi): add DelegatedKey schemas" | Re-trigger Greptile}