openapi: 3.0.1
info:
  title: iVALT Authentication APIs
  version: 1.0.0
  description: >-
    The iVALT Authentication APIs provide secure, real-time user verification
    and session management through a single 1-Click experience. These APIs allow
    developers to authenticate users using mobile biometrics, device identity,
    and contextual factors such as location, IP, time window, and
    organization-defined rules.


    **Core Capabilities:**

    - Verify user identity and device trust

    - Generate and validate authentication tokens

    - Submit biometric and geo-fence data for evaluation

    - Retrieve pass/fail results with factor-level detail

    - Enforce custom authentication policies defined in the iVALT Admin Portal


    Use these endpoints to embed iVALT’s secure authentication workflow directly
    into your web or mobile applications.
  contact:
    name: iVALT Developer Support
    url: https://ivalt.com/support
    email: support@ivalt.com
  license:
    name: Proprietary and Confidential
    url: https://ivalt.com/terms
  termsOfService: https://ivalt.com/terms
tags:
  - name: Auth Apis
    description: >-
      Auth includes operations for verifying user credentials, managing session
      tokens, handling biometric validations, and enforcing geo-fencing rules.
      These APIs ensure secure and compliant access control for both users and
      administrators within the system.
servers:
  - url: https://api.ivalt.com/admin/public/api
    description: Production server
paths:
  /verify-user:
    post:
      summary: Verify user details with encryption
      description: >-
        Endpoint to verify user identity based on country code and mobile number
        with encryption.
      operationId: verifyUser
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: User information required for verification
        content:
          application/json:
            schema:
              type: object
              properties:
                country_code:
                  type: string
                  description: Country code of post /verify-user request.
                  example: '+91'
                mobile:
                  type: string
                  description: Mobile of post /verify-user request.
                  example: '6283974746'
              required:
                - country_code
                - mobile
              description: POST /verify-user request definition.
            example:
              country_code: '+91'
              mobile: '6283974746'
      responses:
        '200':
          description: User verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Verify user details with encryption
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /generate-auth-token:
    post:
      summary: Generate authentication token
      description: Generates an authentication token using client credentials.
      operationId: generateAuthToken
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Client credentials to generate token
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Client id of post /generate-auth-token request.
                client_secret:
                  type: string
                  description: Client secret of post /generate-auth-token request.
              required:
                - client_id
                - client_secret
              description: POST /generate-auth-token request definition.
            example:
              client_id: 964a543a-80cc-4c08-a3a5-f18ce6b3995f
              client_secret: SDbsdKASDssdhw312WAHewweaedhbadasdba
      responses:
        '200':
          description: Token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Generate authentication token
        '400':
          description: Missing or invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /biometric-geo-fence-auth-results:
    post:
      summary: Submit biometric and geo-fence authentication results
      description: Endpoint to submit user biometric and geo-fencing authentication data.
      operationId: postBiometricGeoFenceAuthResults
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Biometric and location data for authentication
        content:
          application/json:
            schema:
              type: object
              properties:
                country_code:
                  type: string
                  description: >-
                    Country code of post /biometric-geo-fence-auth-results
                    request.
                  example: '+91'
                mobile:
                  type: string
                  description: Mobile of post /biometric-geo-fence-auth-results request.
                  example: '6283974746'
                status:
                  type: integer
                  description: Status of post /biometric-geo-fence-auth-results request.
                  example: 1
                latitude:
                  type: string
                  description: Latitude of post /biometric-geo-fence-auth-results request.
                  example: '31.633979'
                longitude:
                  type: string
                  description: Longitude of post /biometric-geo-fence-auth-results request.
                  example: '74.872264'
                address:
                  type: string
                  description: Address of post /biometric-geo-fence-auth-results request.
              required:
                - country_code
                - mobile
                - status
                - latitude
                - longitude
                - address
              description: POST /biometric-geo-fence-auth-results request definition.
            example:
              country_code: '+91'
              mobile: '9530654704'
              status: 1
              latitude: '134564879'
              longitude: '1231232'
              address: Chetanpura
      responses:
        '200':
          description: Authentication results submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Submit biometric and geo-fence authentication results
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /validate-geo-fence-auth:
    post:
      summary: Validate geo-fence authentication
      description: Validates the geo-fence authentication data for a user.
      operationId: validateGeoFenceAuth
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: User location and status information for validation
        content:
          application/json:
            schema:
              type: object
              properties:
                country_code:
                  type: string
                  description: Country code of post /validate-geo-fence-auth request.
                  example: '+91'
                mobile:
                  type: string
                  description: Mobile of post /validate-geo-fence-auth request.
                  example: '6283974746'
                status:
                  type: integer
                  description: Status of post /validate-geo-fence-auth request.
                  example: 1
                latitude:
                  type: string
                  description: Latitude of post /validate-geo-fence-auth request.
                  example: '31.633979'
                longitude:
                  type: string
                  description: Longitude of post /validate-geo-fence-auth request.
                  example: '74.872264'
                address:
                  type: string
                  description: Address of post /validate-geo-fence-auth request.
              required:
                - country_code
                - mobile
                - status
                - latitude
                - longitude
                - address
              description: POST /validate-geo-fence-auth request definition.
            example:
              country_code: '+91'
              mobile: '+916283974746'
              status: 1
              latitude: '134564879'
              longitude: '1231232'
              address: Chetanpura
      responses:
        '200':
          description: Geo-fence authentication validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Validate geo-fence authentication
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /validate-admin-auth:
    post:
      summary: Validate admin authentication
      description: Validates the admin's mobile number for authentication purposes.
      operationId: validateAdminAuth
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Mobile number of the admin for validation
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: Mobile of post /validate-admin-auth request.
                  example: '6283974746'
              required:
                - mobile
              description: POST /validate-admin-auth request definition.
            example:
              mobile: '+916283974746'
      responses:
        '200':
          description: Admin authenticated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Validate admin authentication
        '400':
          description: Invalid mobile number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /validate/global/auth:
    post:
      summary: Validate global authentication
      description: Validates global authentication using mobile number.
      operationId: validateGlobalAuth
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Mobile number for global authentication validation
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: Mobile of post /validate/global/auth request.
                  example: '6283974746'
              required:
                - mobile
              description: POST /validate/global/auth request definition.
            example:
              mobile: '+916283974746'
      responses:
        '200':
          description: Global authentication validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Validate global authentication
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /validate/person:
    post:
      summary: Validate person
      description: Validates a person's mobile number for authentication.
      operationId: validatePerson
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Person's mobile number for validation
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: Mobile of post /validate/person request.
                  example: '6283974746'
              required:
                - mobile
              description: POST /validate/person request definition.
            example:
              mobile: '+916283974746'
      responses:
        '200':
          description: Person validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Validate person
        '400':
          description: Invalid mobile number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /validate/user/timeslots/geofencing:
    post:
      summary: Validate user time slots and geofencing
      description: Validates the time slots and geofence location data of a user.
      operationId: validateUserTimeslotsGeofencing
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: User mobile and longitude data for validation
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: Mobile of post /validate/user/timeslots/geofencing request.
                  example: '6283974746'
                longitude:
                  type: string
                  description: >-
                    Longitude of post /validate/user/timeslots/geofencing
                    request.
                  example: '74.872264'
              required:
                - mobile
                - longitude
              description: POST /validate/user/timeslots/geofencing request definition.
            example:
              mobile: '+916283974746'
              longitude: '74.937933'
      responses:
        '200':
          description: User time slots and geofence validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Validate user time slots and geofencing
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /validate/global/rest/auth:
    post:
      summary: Global REST authentication validation
      description: Validates global REST authentication tokens associated with users.
      operationId: validateGlobalRestAuth
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      parameters: []
      requestBody:
        description: User mobile and authentication token for validation
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: Mobile of post /validate/global/rest/auth request.
                  example: '6283974746'
                auth_token:
                  type: string
                  description: Auth token of post /validate/global/rest/auth request.
              required:
                - mobile
                - auth_token
              description: POST /validate/global/rest/auth request definition.
            example:
              mobile: '+916283974746'
              auth_token: Sample_Token_Example
      responses:
        '200':
          description: Global REST authentication validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Global REST authentication validation
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /api/v1/validate/user:
    post:
      summary: API v1 user validation
      description: >-
        Validates user identity using face authentication and auth tokens for
        API version 1.
      operationId: validateApiV1User
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      parameters: []
      requestBody:
        description: Face authentication token and auth token
        content:
          application/json:
            schema:
              type: object
              properties:
                face_auth_token:
                  type: string
                  description: Face auth token of post /api/v1/validate/user request.
                auth_token:
                  type: string
                  description: Auth token of post /api/v1/validate/user request.
              required:
                - face_auth_token
                - auth_token
              description: POST /api/v1/validate/user request definition.
            example:
              face_auth_token: Sample_Token_Example
              auth_token: Sample_Token_Example
      responses:
        '200':
          description: User successfully validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: API v1 user validation
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /api/v1/auth:
    post:
      summary: API v1 authentication
      description: Authenticates client using client ID and secret for API version 1.
      operationId: authApiV1
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      parameters: []
      requestBody:
        description: Client credentials for authentication
        content:
          application/json:
            schema:
              type: object
              properties:
                client_secret:
                  type: string
                  description: Client secret of post /api/v1/auth request.
                client_id:
                  type: string
                  description: Client id of post /api/v1/auth request.
              required:
                - client_secret
                - client_id
              description: POST /api/v1/auth request definition.
            example:
              client_secret: Sample_Client_token
              client_id: Sample_ClientId
      responses:
        '200':
          description: Client authenticated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: API v1 authentication
        '400':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /api/v1/login/url:
    post:
      summary: Get login URL
      description: Retrieves login URL using authentication token and user details.
      operationId: loginApiV1Url
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      parameters: []
      requestBody:
        description: Authentication token and URLs for login process
        content:
          application/json:
            schema:
              type: object
              properties:
                auth_token:
                  type: string
                  description: Auth token of post /api/v1/login/url request.
                success_url:
                  type: string
                  description: Success url of post /api/v1/login/url request.
                cancel_url:
                  type: string
                  description: Cancel url of post /api/v1/login/url request.
                user_mobile:
                  type: string
                  description: User mobile of post /api/v1/login/url request.
              required:
                - auth_token
                - success_url
                - cancel_url
                - user_mobile
              description: POST /api/v1/login/url request definition.
            example:
              auth_token: Sample_Client_token
              success_url: Sample_ClientId
              cancel_url: Sample_Token_Example
              user_mobile: '6283974746'
      responses:
        '200':
          description: Login URL retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Get login URL
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /api/v1/user/auth/{auth_token}/{uid}:
    get:
      summary: Authenticate user by auth token and UID
      description: Retrieves user authentication status for given auth token and user ID.
      operationId: authApiV1UserAuthTokenUid
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      parameters:
        - name: auth_token
          in: path
          description: Authentication token
          required: true
          schema:
            type: string
            description: >-
              Auth token path parameter for GET
              /api/v1/user/auth/{auth_token}/{uid}.
        - name: uid
          in: path
          description: User ID
          required: true
          schema:
            type: string
            description: Uid path parameter for GET /api/v1/user/auth/{auth_token}/{uid}.
      responses:
        '200':
          description: User authenticated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Authenticate user by auth token and UID
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /get-user-by-email:
    post:
      summary: Retrieve user by email
      description: Fetches user details using their email address.
      operationId: getUserByEmail
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Email address of the user to fetch
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email of post /get-user-by-email request.
              required:
                - email
              description: POST /get-user-by-email request definition.
            example:
              email: bikramjeet1@ivalt.com
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Retrieve user by email
        '400':
          description: Invalid email address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /check-users-existense:
    post:
      summary: Check users existence
      description: Checks the existence of users by mobile numbers.
      operationId: checkUsersExistense
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      requestBody:
        description: List of mobile numbers to check
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile_numbers:
                  type: array
                  items:
                    type: string
                    description: >-
                      POST /check-users-existense request → Mobile numbers item
                      definition.
                  description: Mobile numbers of post /check-users-existense request.
              required:
                - mobile_numbers
              description: POST /check-users-existense request definition.
            example:
              mobile_numbers:
                - '6283974746'
                - '1111111111'
      responses:
        '200':
          description: Users existence checked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Check users existence
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
  /api/v1/redirect/to/merchant/{auth_token}/{mobile}:
    get:
      summary: Redirect to merchant with auth token and mobile
      description: Redirects to a merchant page using auth token and user mobile number.
      operationId: authApiV1UserAuthTokenMobile
      tags:
        - Auth Apis
      security:
        - ApiKeyAuth: []
      parameters:
        - name: auth_token
          in: path
          description: Authentication token
          required: true
          schema:
            type: string
            description: >-
              Auth token path parameter for GET
              /api/v1/redirect/to/merchant/{auth_token}/{mobile}.
        - name: mobile
          in: path
          description: User mobile number
          required: true
          schema:
            type: string
            description: >-
              Mobile path parameter for GET
              /api/v1/redirect/to/merchant/{auth_token}/{mobile}.
      responses:
        '200':
          description: Redirect successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Redirect to merchant with auth token and mobile
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
components:
  schemas:
    SuccessResponse:
      title: Success Response
      type: object
      description: Standard envelope returned for successful requests.
      properties:
        status:
          type: string
          enum:
            - success
          description: Outcome of the request. Always `success` for 2xx responses.
          example: success
        message:
          type: string
          description: Short description of the successful operation outcome.
          example: Operation completed successfully
      required:
        - status
        - message
    ErrorResponse:
      title: Error Response
      type: object
      description: Standard envelope returned for client or server errors.
      properties:
        status:
          type: string
          enum:
            - error
          description: Outcome of the request. Always `error` for 4xx/5xx responses.
          example: error
        message:
          type: string
          description: Detailed explanation of the error to help clients fix the request.
          example: Bad request - missing or invalid data
      required:
        - status
        - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key required in the header. '
security:
  - ApiKeyAuth: []
