add Embedded Wallet Auth endpoints for Email OTP create + verify

.stainless/stainless.yml

@@ -320,6 +320,29 @@ resources:
       list: get /tokens
       retrieve: get /tokens/{tokenId}
       delete: delete /tokens/{tokenId}
+
+  auth:
+    subresources:
+      credentials:
+        methods:
+          create: post /auth/credentials
+          verify: post /auth/credentials/{id}/verify
+        models:
+          auth_method_type: '#/components/schemas/AuthMethodType'
+          auth_method: '#/components/schemas/AuthMethod'
+          auth_session: '#/components/schemas/AuthSession'
+          auth_credential_create_request: '#/components/schemas/AuthCredentialCreateRequest'
+          auth_credential_verify_request: '#/components/schemas/AuthCredentialVerifyRequest'
+          auth_credential_create_request_one_of: '#/components/schemas/AuthCredentialCreateRequestOneOf'
+          auth_credential_verify_request_one_of: '#/components/schemas/AuthCredentialVerifyRequestOneOf'
+          auth_credential_additional_challenge: '#/components/schemas/AuthCredentialAdditionalChallenge'
+          auth_credential_additional_challenge_one_of: '#/components/schemas/AuthCredentialAdditionalChallengeOneOf'
+          email_otp_credential_create_request: '#/components/schemas/EmailOtpCredentialCreateRequest'
+          email_otp_credential_verify_request: '#/components/schemas/EmailOtpCredentialVerifyRequest'
+          email_otp_credential_create_request_fields: '#/components/schemas/EmailOtpCredentialCreateRequestFields'
+          email_otp_credential_verify_request_fields: '#/components/schemas/EmailOtpCredentialVerifyRequestFields'
+          email_otp_credential_additional_challenge: '#/components/schemas/EmailOtpCredentialAdditionalChallenge'
+          email_otp_credential_additional_challenge_fields: '#/components/schemas/EmailOtpCredentialAdditionalChallengeFields'
   exchange_rates:
     methods:
       list:
@@ -807,6 +830,31 @@ openapi:
           - "$.components.schemas.ExternalAccountDetailsTransactionDestination.allOf[0]"
         keys: [ "$ref" ]
 
+    # ── type: auth credential base schemas ──
+    - command: remove
+      reason: >-
+        Remove type $ref from auth credential base schemas so the inline
+        single-value enums in each *CredentialCreateRequestFields /
+        *CredentialVerifyRequestFields / *CredentialAdditionalChallengeFields
+        variant become the sole definition, avoiding allOf type conflicts
+      args:
+        target:
+          - "$.components.schemas.AuthCredentialCreateRequest.properties"
+          - "$.components.schemas.AuthCredentialVerifyRequest.properties"
+          - "$.components.schemas.AuthCredentialAdditionalChallenge.properties"
+        keys: [ "type" ]
+
+    # ── Remove $ref to AuthCredentialVerifyRequest from verify variants ──
+    - command: remove
+      reason: >-
+        Remove allOf $ref to AuthCredentialVerifyRequest from verify variants
+        because the base schema becomes an empty object after stripping the
+        type discriminator (no other shared fields on verify)
+      args:
+        target:
+          - "$.components.schemas.EmailOtpCredentialVerifyRequest.allOf[0]"
+        keys: [ "$ref" ]
+
 codeflow:
   detect_breaking_changes: true
   release_environment: npm

openapi/components/schemas/auth/AuthCredentialAdditionalChallenge.yaml

@@ -0,0 +1,33 @@
+type: object
+required:
+  - type
+  - payloadToSign
+  - requestId
+  - expiresAt
+properties:
+  type:
+    $ref: ./AuthMethodType.yaml
+  payloadToSign:
+    type: string
+    description: >-
+      Payload that must be signed with the session private key of an existing
+      verified authentication credential on the internal account. The resulting
+      signature is passed as the `Grid-Wallet-Signature` header on the retry of
+      `POST /auth/credentials` to complete registration of the additional
+      credential.
+    example: Y2hhbGxlbmdlLXBheWxvYWQtdG8tc2lnbg==
+  requestId:
+    type: string
+    description: >-
+      Unique identifier for this additional-credential registration request.
+      Must be echoed in the `Request-Id` header on the signed retry of
+      `POST /auth/credentials` so the server can correlate the retry with the
+      issued challenge.
+    example: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21
+  expiresAt:
+    type: string
+    format: date-time
+    description: >-
+      Timestamp after which this challenge is no longer valid. The signed retry
+      must be submitted before this time.
+    example: '2026-04-08T15:35:00Z'

openapi/components/schemas/auth/AuthCredentialAdditionalChallengeOneOf.yaml

@@ -0,0 +1,6 @@
+oneOf:
+  - $ref: ./EmailOtpCredentialAdditionalChallenge.yaml
+discriminator:
+  propertyName: type
+  mapping:
+    EMAIL_OTP: ./EmailOtpCredentialAdditionalChallenge.yaml

openapi/components/schemas/auth/AuthCredentialCreateRequest.yaml

@@ -0,0 +1,12 @@
+type: object
+required:
+  - type
+  - accountId
+properties:
+  type:
+    $ref: ./AuthMethodType.yaml
+  accountId:
+    type: string
+    description: >-
+      Identifier of the internal account that this credential will authenticate.
+    example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002

openapi/components/schemas/auth/AuthCredentialCreateRequestOneOf.yaml

@@ -0,0 +1,6 @@
+oneOf:
+  - $ref: ./EmailOtpCredentialCreateRequest.yaml
+discriminator:
+  propertyName: type
+  mapping:
+    EMAIL_OTP: ./EmailOtpCredentialCreateRequest.yaml

openapi/components/schemas/auth/AuthCredentialVerifyRequest.yaml

@@ -0,0 +1,6 @@
+type: object
+required:
+  - type
+properties:
+  type:
+    $ref: ./AuthMethodType.yaml

openapi/components/schemas/auth/AuthCredentialVerifyRequestOneOf.yaml

@@ -0,0 +1,6 @@
+oneOf:
+  - $ref: ./EmailOtpCredentialVerifyRequest.yaml
+discriminator:
+  propertyName: type
+  mapping:
+    EMAIL_OTP: ./EmailOtpCredentialVerifyRequest.yaml

openapi/components/schemas/auth/AuthMethod.yaml

@@ -0,0 +1,37 @@
+type: object
+required:
+  - id
+  - accountId
+  - type
+  - nickname
+  - createdAt
+  - updatedAt
+properties:
+  id:
+    type: string
+    description: System-generated unique identifier for the authentication credential.
+    example: AuthMethod:019542f5-b3e7-1d02-0000-000000000001
+  accountId:
+    type: string
+    description: Identifier of the internal account that this credential authenticates.
+    example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002
+  type:
+    $ref: ./AuthMethodType.yaml
+  nickname:
+    type: string
+    description: >-
+      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: example@lightspark.com
+  createdAt:
+    type: string
+    format: date-time
+    description: Creation timestamp.
+    example: '2026-04-08T15:30:01Z'
+  updatedAt:
+    type: string
+    format: date-time
+    description: Last update timestamp.
+    example: '2026-04-08T15:35:00Z'

openapi/components/schemas/auth/AuthMethodType.yaml

@@ -0,0 +1,14 @@
+type: string
+enum:
+  - OAUTH
+  - EMAIL_OTP
+  - PASSKEY
+description: >-
+  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.

openapi/components/schemas/auth/AuthSession.yaml

@@ -0,0 +1,22 @@
+allOf:
+  - $ref: ./AuthMethod.yaml
+  - type: object
+    required:
+      - encryptedSessionSigningKey
+      - expiresAt
+    properties:
+      encryptedSessionSigningKey:
+        type: string
+        description: >-
+          HPKE-encrypted session signing key, sealed to the `clientPublicKey`
+          supplied when the credential was created. Encoded as a base58check
+          string: the decoded payload is a 33-byte compressed P-256 encapsulated
+          public key followed by AES-256-GCM ciphertext. The client decrypts
+          this key with its private key and uses it to sign subsequent Embedded
+          Wallet requests until `expiresAt`.
+        example: w99a5xV6A75TfoAUkZn869fVyDYvgVsKrawMALZXmrauZd8hEv66EkPU1Z42CUaHESQjcA5bqd8dynTGBMLWB9ewtXWPEVbZvocB4Tw2K1vQVp7uwjf
+      expiresAt:
+        type: string
+        format: date-time
+        description: Timestamp after which the session signing key is no longer valid.
+        example: '2026-04-08T15:35:00Z'

openapi/components/schemas/auth/EmailOtpCredentialAdditionalChallenge.yaml

@@ -0,0 +1,4 @@
+title: Email OTP Credential Additional Challenge
+allOf:
+  - $ref: ./AuthCredentialAdditionalChallenge.yaml
+  - $ref: ./EmailOtpCredentialAdditionalChallengeFields.yaml

openapi/components/schemas/auth/EmailOtpCredentialAdditionalChallengeFields.yaml

@@ -0,0 +1,20 @@
+type: object
+required:
+  - type
+  - email
+properties:
+  type:
+    type: string
+    enum:
+      - EMAIL_OTP
+    description: >-
+      Discriminator value identifying this as an additional-credential
+      challenge for an email OTP credential.
+  email:
+    type: string
+    format: email
+    description: >-
+      Email address associated with the internal account's customer record,
+      returned here so the client knows which mailbox will receive the OTP on
+      the signed retry.
+    example: example@lightspark.com

openapi/components/schemas/auth/EmailOtpCredentialCreateRequest.yaml

@@ -0,0 +1,4 @@
+title: Email OTP Credential Create Request
+allOf:
+  - $ref: ./AuthCredentialCreateRequest.yaml
+  - $ref: ./EmailOtpCredentialCreateRequestFields.yaml

openapi/components/schemas/auth/EmailOtpCredentialCreateRequestFields.yaml

@@ -0,0 +1,9 @@
+type: object
+required:
+  - type
+properties:
+  type:
+    type: string
+    enum:
+      - EMAIL_OTP
+    description: Discriminator value identifying this as an email OTP credential.

openapi/components/schemas/auth/EmailOtpCredentialVerifyRequest.yaml

@@ -0,0 +1,4 @@
+title: Email OTP Credential Verify Request
+allOf:
+  - $ref: ./AuthCredentialVerifyRequest.yaml
+  - $ref: ./EmailOtpCredentialVerifyRequestFields.yaml

openapi/components/schemas/auth/EmailOtpCredentialVerifyRequestFields.yaml

@@ -0,0 +1,25 @@
+type: object
+required:
+  - type
+  - otp
+  - clientPublicKey
+properties:
+  type:
+    type: string
+    enum:
+      - EMAIL_OTP
+    description: Discriminator value identifying this as an email OTP verification.
+  otp:
+    type: string
+    description: The one-time password received by the user via email.
+    example: '123456'
+  clientPublicKey:
+    type: string
+    description: >-
+      Client-generated P-256 public key, hex-encoded in uncompressed SEC1
+      format (0x04 prefix followed by the 32-byte X and 32-byte Y
+      coordinates; 130 hex characters total). The matching private key
+      must remain on the client. Grid encrypts the session signing key
+      returned in the response to this public key. The key is ephemeral
+      and one-time-use per verification request.
+    example: 04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2

openapi/components/schemas/errors/Error400.yaml

@@ -47,6 +47,7 @@ properties:
       | SUSPECTED_FRAUD | Document suspected of being forged or edited |
       | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported |
       | INCOMPLETE | Document is missing pages or sides |
+      | EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time |
     enum:
       - INVALID_INPUT
       - MISSING_MANDATORY_USER_INFO
@@ -81,6 +82,7 @@ properties:
       - SUSPECTED_FRAUD
       - UNSUITABLE_DOCUMENT
       - INCOMPLETE
+      - EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS
   message:
     type: string
     description: Error message