Sign in

v5

latestOpenAPI 3.1.0Proprietary2026-08-011476181.4 MB
Embedded Wallet Auth

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 (decrypted client-side from its encryptedSessionSigningKey) 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

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

Authentication credential created successfully. The body is the created AuthMethod. For EMAIL_OTP, the nickname is the customer email tied to the internal account; for SMS_OTP, it is the customer phone number. OTP responses that trigger a secure OTP challenge carry otpEncryptionTargetBundle — the HPKE target bundle the client uses to encrypt the OTP attempt on the subsequent POST /auth/credentials/{id}/verify. First-time EMAIL_OTP wallet bootstrap responses may omit that bundle; if it is absent, call POST /auth/credentials/{id}/challenge for the new credential to issue a fresh OTP and receive otpEncryptionTargetBundle before verifying. For PASSKEY, the credential must be authenticated for the first time via POST /auth/credentials/{id}/challenge followed by POST /auth/credentials/{id}/verify to produce a session — there is no inline authentication challenge on the registration response.

idstring required

System-generated unique identifier for the authentication credential.

accountIdstring required

Identifier of the internal account that this credential authenticates.

type'OAUTH' | 'EMAIL_OTP' | 'SMS_OTP' | 'PASSKEY' required

The type of authentication credential.

  • OAUTH: OpenID Connect (OIDC) token issued by an identity provider such as Google or Apple.
  • EMAIL_OTP: A one-time password delivered to the user's email address.
  • SMS_OTP: A one-time password delivered to the user's phone number.
  • PASSKEY: A WebAuthn passkey bound to the user's device.
credentialIdstring

Base64url-encoded WebAuthn credential identifier for this passkey. Present only for PASSKEY authentication credentials. Corresponds to PublicKeyCredential.rawId; pass this value as allowCredentials[].id when requesting a passkey assertion for this auth method.

nicknamestring required

Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for SMS_OTP credentials this is the E.164 phone number; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the validated nickname provided at registration time.

createdAtstring date-time required

Creation timestamp.

updatedAtstring date-time required

Last update timestamp.

otpEncryptionTargetBundlestring

HPKE encryption target bundle for a freshly initiated OTP challenge. Returned only on EMAIL_OTP and SMS_OTP responses that initiate or reissue an OTP challenge, such as POST /auth/credentials/{id}/challenge and signed-retry add responses. It is omitted from first-time EMAIL_OTP wallet bootstrap registration; call POST /auth/credentials/{id}/challenge for the new credential if it is absent. The client generates an ephemeral P-256 keypair (the Target Encryption Key, or TEK) and uses this bundle as the recipient when HPKE-encrypting {otp_code, public_key}; the encrypted payload is submitted as encryptedOtpBundle on POST /auth/credentials/{id}/verify. The bundle is one-time-use per OTP issuance — re-issue via POST /auth/credentials/{id}/challenge to obtain a fresh bundle. The matching TEK private key must remain on the client and is used to sign the verificationToken returned on the subsequent signed-retry. Treat the bundle as opaque and pass it to your HPKE library; the Global Accounts client-keys guide shows how.

Example response

{
  "id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "credentialId": "KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew",
  "nickname": "example@lightspark.com",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:35:00Z",
  "otpEncryptionTargetBundle": "{\"version\":\"v1.0.0\",\"data\":\"7b227461726765745075626c6963...\",\"dataSignature\":\"30450221...\",\"enclaveQuorumPublic\":\"04a1b2c3...\"}"
}