> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate user authentication

> Initiate authentication for a user. If the email address is for a new user, a new onboard profile will be created




## OpenAPI

````yaml post /auth/user-auth/initiate
openapi: 3.0.3
info:
  version: 2.1.0
  title: Onboard External API Gateway
  description: >-
    **Introduction**

    API Gateway for Onboard


    This specification describes API endpoints that are available to the public
    internet via the API gateway. The different endpoints require different
    authentication schemes, see documentation for what applies to the operation
    you want to access.


    **Errors**

    Uses conventional HTTP response codes to indicate success or failure. In

    general:
     
    - `2xx` status codes indicate success. Codes in the

    - `4xx` range

    indicate a client error (e.g. required parameters, failed request etc.).

    - `5xx` status codes indicate a server error occurred.
  contact:
    name: Nestcoin TechOps
    email: techops@nestcoin.com
  license:
    name: UNLICENSED
servers:
  - url: https://external.dev.onboardpay.co
    description: Gateway for external API on staging environment.
security: []
tags:
  - name: users-onboardapi
    description: Endpoints available to for merchants liquidity automation
  - name: users-users
    description: User related endpoints
  - name: users-partners
    description: Partner related endpoints
  - name: users-admin
    description: Back office related endpoints
  - name: users-user2fa
    description: User 2fa related endpoints
  - name: users-usernotifications
    description: User notifications related endpoints
  - name: users-merchantnetwork
    description: Merchant network endpoints
  - name: users-userauth
    description: Authentication endpoints
  - name: users-userservice
    description: Service endpoints
  - name: users-webhook
    description: webhook endpoints
paths:
  /auth/user-auth/initiate:
    post:
      tags:
        - auth-userauth
      summary: Initiate authentication for a user
      description: >
        Initiate authentication for a user. If the email address is for a new
        user, a new onboard profile will be created
      operationId: initiateUserLogin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAuthInitRequest'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAuthInitResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
      security:
        - authSignature: []
components:
  schemas:
    UserAuthInitRequest:
      required:
        - email
      type: object
      properties:
        email:
          type: string
          description: user's email
    UserAuthInitResponse:
      type: object
      properties:
        authSessionId:
          type: string
          description: >-
            The log in session ID of the user, valid for the duration of the OTP
            validity
          format: uuid
        isReturning:
          type: boolean
          description: Indicates if user is a returning user, i.e. previously verified
          default: false
    ErrorMessageDto:
      description: >-
        Default error object for services. This gives consistent error object
        that all services may use.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
          example: UNKNOWN_ERROR
        message:
          type: string
          description: Descriptive error message
          example: Request could not be completed due to an error
        data:
          type: object
          description: Additional data for this error message.
          additionalProperties: true
          properties: {}
      x-common-model: ErrorMessageDto
  securitySchemes:
    authSignature:
      type: apiKey
      name: x-signature
      in: header

````