diff --git a/openapi/components/schemas/auth/DelegatedKey.yaml b/openapi/components/schemas/auth/DelegatedKey.yaml new file mode 100644 index 000000000..aaffa1baa --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKey.yaml @@ -0,0 +1,54 @@ +title: Delegated Key +type: object +required: + - id + - cardId + - accountId + - publicKey + - nickname + - status + - createdAt + - updatedAt +description: >- + A delegated signing key for a card backed by 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 card's + Embedded Wallet funding account 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 + cardId: + type: string + description: The card this key is delegated for. + example: Card:019542f5-b3e7-1d02-0000-000000000010 + accountId: + type: string + description: >- + The Embedded Wallet internal account this key is delegated for, + derived from the card's funding sources. + 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/DelegatedKeyCreateRequest.yaml b/openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml new file mode 100644 index 000000000..12cc17623 --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeyCreateRequest.yaml @@ -0,0 +1,19 @@ +title: Delegated Key Create Request +type: object +required: + - cardId + - nickname +properties: + cardId: + type: string + description: >- + The id of the card that will use this delegated signing key. Grid + derives the Embedded Wallet funding source from the card and creates + the key for that card's wallet funding account. + example: Card:019542f5-b3e7-1d02-0000-000000000010 + nickname: + type: string + minLength: 1 + maxLength: 256 + description: Human-readable label for the delegated key. + example: Card payments key diff --git a/openapi/components/schemas/auth/DelegatedKeyListResponse.yaml b/openapi/components/schemas/auth/DelegatedKeyListResponse.yaml new file mode 100644 index 000000000..96c77e2fb --- /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: Delegated signing keys matching the list filters. + 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 000000000..14e20ec8a --- /dev/null +++ b/openapi/components/schemas/auth/DelegatedKeySignedRequestChallenge.yaml @@ -0,0 +1,8 @@ +title: Delegated Key Signed Request Challenge +description: >- + 202 response returned from the delegated-key endpoints. Stamp `payloadToSign` + with the session API keypair of a verified credential on the delegated key's + Embedded Wallet funding 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 diff --git a/openapi/components/schemas/auth/DelegatedKeyStatus.yaml b/openapi/components/schemas/auth/DelegatedKeyStatus.yaml new file mode 100644 index 000000000..c88f72fc0 --- /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