Embedded Wallet Auth

Create a delegated signing key

Changed on

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.

post/auth/delegated-keys

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys
  • Auth: HTTP basic

Headers

Grid-Wallet-Signaturestring

Full API-key stamp built over the prior payloadToSign with the session API keypair of a verified credential on the same internal account. Required on the signed retries; ignored on the initial call.

Request-Idstring

The requestId returned in the prior 202 response, echoed back exactly on the signed retry so the server can correlate it with the issued challenge. Required on the signed retries; must be paired with Grid-Wallet-Signature.

Request body

cardIdstring required

The id of the card whose Embedded Wallet funding account will use this delegated signing key.

internalAccountIdstring 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.

nicknamestring required

Human-readable label for the delegated key.

Example request

{
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "internalAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "nickname": "Card payments key"
}

Response

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.

idstring required

Grid-issued DelegatedKey:<uuid> identifier.

cardIdstring required

The card this key is delegated for.

fundingSourceIdstring required

The card funding source this key is delegated for.

accountIdstring required

The Embedded Wallet internal account this key is delegated for, derived from the card funding source.

publicKeystring required

Compressed P-256 public key (hex) of the delegated API keypair.

nicknamestring 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.
createdAtstring date-time required

When the delegated key was created.

updatedAtstring date-time required

When the delegated key was last updated.

Example response

{
  "id": "DelegatedKey:019542f5-b3e7-1d02-0000-000000000021",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "fundingSourceId": "CardFundingSource:019542f5-b3e7-1d02-0000-000000000011",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "publicKey": "02a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "nickname": "Settlement service key",
  "status": "ACTIVE",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:30:42Z"
}

Changes

  • 3966e5d38aadRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new DOCUMENT_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new DUPLICATE_EXTERNAL_ACCOUNT enum value to the response property for the response status

    • warning

      added the new DUPLICATE_PAY_REQUEST enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_FUNDS enum value to the response property for the response status

    • warning

      added the new NOT_FOUND enum value to the response property for the response status

    • warning

      added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new PLATFORM_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new QUOTE_EXPIRED enum value to the response property for the response status

    • warning

      added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status

    • warning

      added the new REQUEST_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new SESSION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new SMS_OTP_CREDENTIAL_SET_CHANGED enum value to the response property for the response status

    • warning

      added the new SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_SYMBOL_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status

    • warning

      added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new WALLET_NOT_PROVISIONED enum value to the response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • ccf658daca4bRevision changes
    • warning

      added the new BANK_ACCOUNT_VALIDATION_PENDING enum value to the response property for the response status