openapi: 3.0.0
paths:
  /v1/onboarding-token:
    post:
      description: >-
        Create a unique onboarding token (OT) for an end-user, email it to them
        using the standard onboarding template, and return the token in the
        response
      operationId: createOnboardingToken
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOnboardingTokenDto'
      responses:
        '201':
          description: >-
            Onboarding token has been successfully created and submitted to the
            client via Email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOnboardingTokenResponse'
        '400':
          description: Validation errors or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOnboardingTokenErrorDto'
        '401':
          description: Authentication required or failed. Please provide valid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorDto'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorDto'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorDto'
        '409':
          description: >-
            The request could not be completed due to a conflict with the
            current state of the resource (e.g., duplicate entry).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorDto'
        5XX:
          description: >-
            Internal error during the process. Please reach out to support so we
            can help you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorDto'
      security:
        - bearer: []
      summary: Create onboarding token
      tags:
        - Onboarding Token
info:
  title: Onboarding Token API
  description: >-
    This API enables customers to programmatically generate unique onboarding
    tokens (OT) for end-users,
          following existing onboarding logic, and automatically email the token to the user.
          Tokens are created with a 14-day expiration, conflict detection, and standard state handling (Issued, Used, Expired).
          Issued tokens are recorded in the organization's dashboard.
  version: '1.0'
  contact:
    name: SQR
    url: https://sqr.id
    email: support@sqr.id
tags:
  - name: Onboarding Token
    description: >-
      — This API allows customers to programmatically create onboarding tokens
      and email them to end-users.
servers:
  - url: https://api.sqr-group.com
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
  schemas:
    CreateOnboardingTokenDto:
      type: object
      properties:
        email:
          type: string
          description: Email Address of the user
          example: john.doe@sqr-group.com
        first_name:
          type: string
          description: First name of the user
          example: John
        last_name:
          type: string
          description: Last name of the user
          example: Doe
      required:
        - email
        - first_name
        - last_name
    CreateOnboardingTokenResponse:
      type: object
      properties:
        onboarding_token:
          type: string
          readOnly: true
          example: SNFF3I2
          description: The onboarding token created by admin.
    ErrorDetailSchema:
      type: object
      properties:
        field:
          type: string
          example: email
        code:
          type: string
          example: isNotEmpty
        hint:
          type: string
          example: email should not be empty
    CreateOnboardingTokenErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 400
        errors:
          example:
            - field: email
              code: isNotEmpty
              hint: email should not be empty
            - field: firstName
              code: isNotEmpty
              hint: firstName should not be empty
            - field: lastName
              code: isNotEmpty
              hint: lastName should not be empty
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailSchema'
      required:
        - code
        - errors
    UnauthorizedErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 401
          readOnly: true
        timestamp:
          format: date-time
          type: string
          example: '2025-07-11T06:51:25.202Z'
          readOnly: true
        path:
          type: string
          example: /api/v1/[route]...
          readOnly: true
        method:
          type: string
          example: GET
          readOnly: true
        error:
          type: string
          example: UNAUTHORIZED
          readOnly: true
        message:
          type: string
          example: Unauthorized
          readOnly: true
      required:
        - code
        - timestamp
        - path
        - method
        - error
        - message
    ForbiddenErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 403
          readOnly: true
        timestamp:
          format: date-time
          type: string
          example: '2025-07-11T06:51:25.202Z'
          readOnly: true
        path:
          type: string
          example: /api/v1/[route]...
          readOnly: true
        method:
          type: string
          example: GET
          readOnly: true
        error:
          type: string
          example: FORBIDDEN
          readOnly: true
        message:
          type: string
          example: Forbidden
          readOnly: true
      required:
        - code
        - timestamp
        - path
        - method
        - error
        - message
    NotFoundErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 404
          readOnly: true
        timestamp:
          format: date-time
          type: string
          example: '2025-07-11T06:51:25.202Z'
          readOnly: true
        path:
          type: string
          example: /api/v1/[route]...
          readOnly: true
        method:
          type: string
          example: GET
          readOnly: true
        error:
          type: string
          example: NOT_FOUND
          readOnly: true
        message:
          type: string
          example: Cannot GET /api/v1
          readOnly: true
      required:
        - code
        - timestamp
        - path
        - method
        - error
        - message
    ConflictErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 409
          readOnly: true
        timestamp:
          format: date-time
          type: string
          example: '2025-07-11T06:51:25.202Z'
          readOnly: true
        path:
          type: string
          example: /api/v1/[route]...
          readOnly: true
        method:
          type: string
          example: GET
          readOnly: true
        error:
          type: string
          example: CONFLICT
          readOnly: true
        message:
          type: string
          example: Conflict
          readOnly: true
      required:
        - code
        - timestamp
        - path
        - method
        - error
        - message
    InternalErrorDto:
      type: object
      properties:
        code:
          type: number
          example: 503
          readOnly: true
        timestamp:
          format: date-time
          type: string
          example: '2025-07-11T06:51:25.202Z'
          readOnly: true
        path:
          type: string
          example: /api/v1/[route]...
          readOnly: true
        method:
          type: string
          example: GET
          readOnly: true
        error:
          type: string
          example: INTERNAL_SERVER_ERROR
          readOnly: true
        message:
          type: string
          example: Internal Server Error
          readOnly: true
      required:
        - code
        - timestamp
        - path
        - method
        - error
        - message
