Embedded Wallet Auth

Create an authentication credential

Changed on

Register an authentication credential for an Embedded Wallet customer.

Embedded Wallet internal accounts are initialized with an EMAIL_OTP credential tied to the customer email on the account. Use this endpoint to add another credential (SMS_OTP, OAUTH, or PASSKEY), or to add EMAIL_OTP / SMS_OTP back after it has been removed. Only one EMAIL_OTP and one SMS_OTP credential are supported per internal account; multiple distinct PASSKEY credentials may be registered.

Adding a credential requires a signature from an existing verified credential on the same account. Call this endpoint with the new credential's details to receive 202 with payloadToSign and requestId. Use the session API keypair of an existing verified credential (the session signing key the client holds for it) 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 signed retry returns 201 with the created AuthMethod. For OTP credentials, the one-time password is triggered on the signed retry, and the credential must then be activated via POST /auth/credentials/{id}/verify.

post/auth/credentials

Request

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

Headers

Grid-Wallet-Signaturestring

Full API-key stamp built over the prior payloadToSign with the session API keypair of an existing verified authentication credential on the target internal account. Required on the signed retry.

Request-Idstring

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

Request body

OR
OR
OR

Example request

{
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}

Response

An additional-credential setup leg's underlying wallet-provider activity is still in flight — a WalletOperationProcessing body with status: "PROCESSING". The client re-sends the byte-identical stamped retry (same Request-Id) until the credential is added; the backend also reconciles the activity to terminal on its own.

status'PROCESSING' required

Always PROCESSING. Marks a still-in-flight operation whose terminal result is not yet available.

messagestring

Human-readable explanation that the operation is still being processed and the same request may be retried.

Example response

{
  "status": "PROCESSING",
  "message": "This login is still being processed. Retry the same request in a moment."
}

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

    • 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_HOLDER_NOT_FOUND 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 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_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

    • 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

  • 8964d9c7b6f9Revision changes
    • info

      added the success response with the status