Create an authentication credential

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

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/auth/credentials \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "EMAIL_OTP",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}
'

200

Example

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

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature · string

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-Id · string

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.

Body

application/json

Email OTP Credential Create Request

SMS OTP Credential Create Request

OAuth Credential Create Request

Passkey Credential Create Request

type · enum<string> · required

Discriminator value identifying this as an email OTP credential.

Available options: EMAIL_OTP

accountId · string · required

Identifier of the internal account that this credential will authenticate.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

Response

200

application/json

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.

200 response returned by an Embedded Wallet operation that the wallet provider has accepted but not yet settled — a consensus- or approval-gated activity that is still in flight. It is not an error and needs no client action beyond patience: the backend reconciles the operation to its terminal state on its own. The client MAY re-send the byte-identical request to converge sooner; the request is idempotent and returns the settled success response once the operation completes.

status · enum<string> · required

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

Available options: PROCESSING

Example:

"PROCESSING"

message · string

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

Example:

"This login is still being processed. Retry the same request in a moment."