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"
}
'{
"id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"type": "OAUTH",
"nickname": "example@lightspark.com",
"createdAt": "2026-04-08T15:30:01Z",
"updatedAt": "2026-04-08T15:35:00Z"
}Create an authentication credential
Register an authentication credential for an Embedded Wallet customer.
First credential on an internal account
If the target internal account does not yet have any authentication credential registered, call this endpoint with the credential details. The response is 201 with the created AuthMethod. For EMAIL_OTP credentials, this call also triggers a one-time password email to the address on the customer record tied to the internal account; the credential must be activated via POST /auth/credentials/{id}/verify before it can sign requests.
Adding an additional credential
Registering an additional credential against an internal account that already has one requires a signature from an existing verified credential. Call this endpoint with the new credential’s details; if an existing credential is already registered on the internal account the response is 202 with a payloadToSign and a requestId. Sign the payload with the session private key of an existing verified credential on the same internal account (decrypted client-side from its encryptedSessionSigningKey) and retry the same request with the signature supplied 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 EMAIL_OTP, the OTP email is triggered on the signed retry, and the credential must then be activated via POST /auth/credentials/{id}/verify.
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"
}
'{
"id": "AuthMethod:019542f5-b3e7-1d02-0000-000000000001",
"accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"type": "OAUTH",
"nickname": "example@lightspark.com",
"createdAt": "2026-04-08T15:30:01Z",
"updatedAt": "2026-04-08T15:35:00Z"
}Authorizations
API token authentication using format <api token id>:<api client secret>
Headers
Signature over the payloadToSign returned in a prior 202 response, produced with the session private key of an existing verified authentication credential on the target internal account and base64-encoded. Required when registering an additional credential on an internal account that already has one; ignored when the internal account has no existing credentials.
The requestId returned in a prior 202 response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry when registering an additional credential; must be paired with Grid-Wallet-Signature.
Body
Response
Authentication credential created successfully
System-generated unique identifier for the authentication credential.
"AuthMethod:019542f5-b3e7-1d02-0000-000000000001"
Identifier of the internal account that this credential authenticates.
"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
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.PASSKEY: A WebAuthn passkey bound to the user's device.
OAUTH, EMAIL_OTP, PASSKEY Human-readable identifier for this credential. For EMAIL_OTP credentials this is the email address; for OAUTH credentials it is typically the email claim from the OIDC token; for PASSKEY credentials it is the nickname provided at registration time.
"example@lightspark.com"
Creation timestamp.
"2026-04-08T15:30:01Z"
Last update timestamp.
"2026-04-08T15:35:00Z"
Was this page helpful?