From de24d16f189a74e6977b792241539956781e0650 Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Thu, 11 Jun 2026 11:19:20 -0700 Subject: [PATCH] feat(openapi): add DelegatedKey schemas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Component schemas for the upcoming /auth/delegated-keys endpoints: DelegatedKeyCreateRequest, DelegatedKey, DelegatedKeyStatus, DelegatedKeyListResponse, DelegatedKeyChallengeStep, and DelegatedKeySignedRequestChallenge (SignedRequestChallenge + step). Schemas only — not yet referenced by any path, so the generated bundle is unchanged. Endpoints land in the next PR up the stack. --- .../components/schemas/auth/DelegatedKey.yaml | 47 +++++++++++++++++++ .../auth/DelegatedKeyChallengeStep.yaml | 11 +++++ .../auth/DelegatedKeyCreateRequest.yaml | 18 +++++++ .../auth/DelegatedKeyListResponse.yaml | 10 ++++ .../DelegatedKeySignedRequestChallenge.yaml | 17 +++++++ .../schemas/auth/DelegatedKeyStatus.yaml | 17 +++++++ 6 files changed, 120 insertions(+) create mode 100644 openapi/components/schemas/auth/DelegatedKey.yaml create mode 100644 openapi/components/schemas/auth/DelegatedKeyChallengeStep.yaml create mode 100644 openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml create mode 100644 openapi/components/schemas/auth/DelegatedKeyListResponse.yaml create mode 100644 openapi/components/schemas/auth/DelegatedKeySignedRequestChallenge.yaml create mode 100644 openapi/components/schemas/auth/DelegatedKeyStatus.yaml diff --git a/openapi/components/schemas/auth/DelegatedKey.yaml b/openapi/components/schemas/auth/DelegatedKey.yaml new file mode 100644 index 00000000..52b0f3ac --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKey.yaml @@ -0,0 +1,47 @@ +title: Delegated Key +type: object +required: + - id + - accountId + - publicKey + - nickname + - status + - createdAt + - updatedAt +description: >- + A delegated signing key on an Embedded Wallet internal account. Returned + from `POST /auth/delegated-keys` (on activation) and + `GET /auth/delegated-keys` (list). The keypair is generated and custodied + by Grid; the private key is never returned. While `ACTIVE`, Grid may use + the key to authorize Spark token-transaction signing for the account + (e.g. when the user requests a payment) in place of a session keypair. + `publicKey` is informational metadata identifying the credential. +properties: + id: + type: string + description: Grid-issued `DelegatedKey:` identifier. + example: DelegatedKey:019542f5-b3e7-1d02-0000-000000000021 + accountId: + type: string + description: The internal account this key is delegated for. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + publicKey: + type: string + description: Compressed P-256 public key (hex) of the delegated API keypair. + example: 02a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90 + nickname: + type: string + description: Human-readable label for the delegated key. + example: Settlement service key + status: + $ref: ./DelegatedKeyStatus.yaml + createdAt: + type: string + format: date-time + description: When the delegated key was created. + example: '2026-04-08T15:30:01Z' + updatedAt: + type: string + format: date-time + description: When the delegated key was last updated. + example: '2026-04-08T15:30:42Z' diff --git a/openapi/components/schemas/auth/DelegatedKeyChallengeStep.yaml b/openapi/components/schemas/auth/DelegatedKeyChallengeStep.yaml new file mode 100644 index 00000000..75203ebc --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeyChallengeStep.yaml @@ -0,0 +1,11 @@ +type: string +enum: + - CREATE_USER + - CREATE_POLICY + - DELETE_USER + - DELETE_POLICY +description: >- + Which signer activity the requested stamp will authorize: `CREATE_USER` / + `CREATE_POLICY` during creation (`POST /auth/delegated-keys`), + `DELETE_USER` / `DELETE_POLICY` during revocation + (`DELETE /auth/delegated-keys/{id}`). diff --git a/openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml b/openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml new file mode 100644 index 00000000..fb9806ae --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml @@ -0,0 +1,18 @@ +title: Delegated Key Create Request +type: object +required: + - accountId + - nickname +properties: + accountId: + type: string + description: >- + The id of the Embedded Wallet internal account delegating signing + authority. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + nickname: + type: string + minLength: 1 + maxLength: 256 + description: Human-readable label for the delegated key. + example: Recurring payments key diff --git a/openapi/components/schemas/auth/DelegatedKeyListResponse.yaml b/openapi/components/schemas/auth/DelegatedKeyListResponse.yaml new file mode 100644 index 00000000..aeb08541 --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeyListResponse.yaml @@ -0,0 +1,10 @@ +title: Delegated Key List Response +type: object +required: + - data +properties: + data: + type: array + description: The delegated signing keys on the account. + items: + $ref: ./DelegatedKey.yaml diff --git a/openapi/components/schemas/auth/DelegatedKeySignedRequestChallenge.yaml b/openapi/components/schemas/auth/DelegatedKeySignedRequestChallenge.yaml new file mode 100644 index 00000000..3afac116 --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeySignedRequestChallenge.yaml @@ -0,0 +1,17 @@ +title: Delegated Key Signed Request Challenge +description: >- + 202 response returned from the delegated-key endpoints. Carries the + signing fields from `SignedRequestChallenge` plus the `step` identifying + which signer activity the client is being asked to authorize. Stamp + `payloadToSign` with the session API keypair of a verified credential on + the same internal account, then retry the same request with the full + stamp in `Grid-Wallet-Signature` and the `requestId` echoed in + `Request-Id`. +allOf: + - $ref: ../common/SignedRequestChallenge.yaml + - type: object + required: + - step + properties: + step: + $ref: ./DelegatedKeyChallengeStep.yaml diff --git a/openapi/components/schemas/auth/DelegatedKeyStatus.yaml b/openapi/components/schemas/auth/DelegatedKeyStatus.yaml new file mode 100644 index 00000000..c88f72fc --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeyStatus.yaml @@ -0,0 +1,17 @@ +type: string +enum: + - PENDING + - ACTIVE + - REVOKED +description: >- + Status of a delegated signing key. + + + - `PENDING`: The delegated user exists but the policy-creation leg never + completed. The key cannot sign. + + - `ACTIVE`: The policy is granted and the key may stamp quote executions. + + - `REVOKED`: The delegated user has been deleted and the key can no + longer sign. +example: ACTIVE