--- title: "Create a delegated signing key" method: POST path: "/auth/delegated-keys" tags: ["Embedded Wallet Auth"] --- # Create a delegated signing key `POST /auth/delegated-keys` Delegate Spark token-transaction signing authority for a card funding source backed by an Embedded Wallet internal account to a Grid-custodied P-256 API key. Grid uses the requested card and internal account to identify the wallet funding source, generates the keypair server-side, creates an isolated signer identity holding the public key, then policies granting that identity signing and self-revocation authority. The private key is custodied by Grid and never returned. Both activities must be authorized by the wallet owner, so creation is a three-leg signed-retry flow: 1. Call `POST /auth/delegated-keys` with no signature headers. Grid generates the delegated keypair and the response is `202` with a `payloadToSign`, `requestId`, and `expiresAt`. 2. Use the session API keypair of a verified credential on the requested Embedded Wallet internal account to build an API-key stamp over `payloadToSign`, then retry the same request with that full stamp as the `Grid-Wallet-Signature` header and the `requestId` echoed back as the `Request-Id` header. The response is a second `202` with a new `payloadToSign`, `requestId`, and `expiresAt`. 3. Stamp the new `payloadToSign` with the same session keypair and retry once more with the new `Request-Id`. The signed retry returns `201` with the created `DelegatedKey` in `ACTIVE` status. The same request body must be sent on all three legs. A flow abandoned after the second leg leaves the key in `PENDING` status: the signer identity exists but holds no policies, so it cannot sign or revoke itself. Abandoned `PENDING` keys do not block creating another delegated key. After activation, Grid uses the custodied key to authorize signing for the card's Embedded Wallet funding account in place of a session keypair; the platform never handles the key material. Each card funding source may have at most one `ACTIVE` delegated key for its Embedded Wallet funding account; revoke the existing active key before creating a new one. A delegated key authorizes raw-payload signing for the wallet and cannot be scoped to amounts or recipients by the public API. Revoke it with `DELETE /auth/delegated-keys/{id}` when no longer needed. ## Headers - `Grid-Wallet-Signature` string - `Request-Id` string ## Request body - DelegatedKeyCreateRequest - `cardId` string, required — The id of the card whose Embedded Wallet funding account will use this delegated signing key. - `internalAccountId` string, required — The id of the Embedded Wallet internal account funding the card. Grid uses the `(cardId, internalAccountId)` pair to find the active card funding-source binding. - `nickname` string, required — Human-readable label for the delegated key. - `spendingLimits` DelegatedKeySpendingLimit[] — Optional per-transaction spending limits for the key, at most one entry per currency — a request with duplicate currency entries is rejected. Grid enforces the limits when authorizing card transactions funded by the key's Embedded Wallet account; a currency with no entry is unlimited. Immutable — revoke the key and create a new one to change limits. - `currencyCode` string, required — Uppercase alphanumeric currency code the limit applies to — ISO 4217 for fiat (e.g. USD), or a Grid token code for stablecoins (e.g. USDB). Must match the card's currency; requests with any other currency are rejected. - `maxPerTransaction` integer, required — Largest amount a single card transaction may authorize, in the smallest unit of the currency (e.g., cents for USD). ## Response `201` Delegated key created and policy granted. The key is `ACTIVE` and Grid may use it to stamp card-payment quote executions for this card funding source's Embedded Wallet funding account. - DelegatedKey — A delegated signing key for a card funding source backed by an Embedded Wallet internal account. Returned from `POST /auth/delegated-keys` (on activation), `GET /auth/delegated-keys` (list), and `GET /auth/delegated-keys/{id}`. 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 funding source's Embedded Wallet funding account in place of a session keypair. `publicKey` is informational metadata identifying the credential. - `id` string, required — Grid-issued `DelegatedKey:` identifier. - `cardId` string, required — The card this key is delegated for. - `fundingSourceId` string, required — The card funding source this key is delegated for. - `accountId` string, required — The Embedded Wallet internal account this key is delegated for, derived from the card funding source. - `publicKey` string, required — Compressed P-256 public key (hex) of the delegated API keypair. - `nickname` string, required — Human-readable label for the delegated key. - `status` 'PENDING' | 'ACTIVE' | 'REVOKED', required — 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. - `spendingLimits` DelegatedKeySpendingLimit[] — Per-transaction spending limits the key was created with, at most one entry per currency. Absent when the key has no limits. - `currencyCode` string, required — Uppercase alphanumeric currency code the limit applies to — ISO 4217 for fiat (e.g. USD), or a Grid token code for stablecoins (e.g. USDB). Must match the card's currency; requests with any other currency are rejected. - `maxPerTransaction` integer, required — Largest amount a single card transaction may authorize, in the smallest unit of the currency (e.g., cents for USD). - `createdAt` string, date-time, required — When the delegated key was created. - `updatedAt` string, date-time, required — When the delegated key was last updated. ## Other responses - `202` — Challenge issued for the next leg. Stamp `payloadToSign` and retry the same request with `Grid-Wallet-Signature` and `Request-Id`. - `400` — Bad request - `401` — Unauthorized. Returned when the provided `Grid-Wallet-Signature` is missing on a retry, malformed, or does not match the pending challenge, or when the `Request-Id` does not match an unexpired pending challenge. - `404` — Card, card funding source, or Embedded Wallet funding account not found - `409` — An `ACTIVE` delegated key already exists for this card funding source. Revoke it with `DELETE /auth/delegated-keys/{id}` before creating a new one. - `500` — Internal service error --- [API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/151f2d9bad9c/schema)