Dream Sports Passwordless API

openapi: 3.2.0
info:
  title: Guardian Passwordless API
  version: 1.0.0
tags:
- name: Passwordless
paths:
  /v1/passwordless/init:
    post:
      tags:
      - Passwordless
      summary: Initiate the passwordless flow
      description: 'API to signin, signup or signinup a user using passwordless flows. Currently only otp based passwordless flow is supported.


        The first time this API is called, a unique state is returned in the response. Every subsequent request to init (to resend otp), must include the state parameter in the request, otherwise it is treated as a fresh request.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1PasswordlessInitRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully sent an OTP
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/State'
        '400':
          description: Bad Request due to missing parameters or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/passwordless/complete:
    post:
      tags:
      - Passwordless
      summary: Complete the passwordless flow
      description: 'API to signin, signup or signinup a user using passwordless flows. Currently only otp based passwordless flow is supported.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1PasswordlessCompleteRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully signed in or up
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad Request due to missing parameters or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/passwordless/init:
    post:
      tags:
      - Passwordless
      summary: Initiate the passwordless flow
      description: 'API to signin, signup or signinup a user using passwordless flows. Currently only otp based passwordless flow is supported.


        The first time this API is called, a unique state is returned in the response. Every subsequent request to init (to resend otp), must include the state parameter in the request, otherwise it is treated as a fresh request.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PasswordlessInitRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully sent an OTP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PasswordlessInitResponse'
        '400':
          description: Bad Request due to missing parameters or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/passwordless/complete:
    post:
      tags:
      - Passwordless
      summary: Complete the passwordless flow
      description: 'API to signin, signup or signinup a user using passwordless flows. Currently only otp based passwordless flow is supported.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1PasswordlessCompleteRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully signed in or up
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2TokenResponse'
          headers:
            Set-Cookie:
              description: Sets authentication cookies (access token, refresh token, SSO token)
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Bad Request due to missing parameters or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/otp/send:
    post:
      tags:
      - Passwordless
      summary: Send OTP for contact verification
      description: "API to send OTP to a contact (SMS or Email) for verification purposes. This is independent of the authentication flow and can be used for various contact verification scenarios.\n\n**First Request**: Send contact details to initiate OTP sending. A unique state is returned.\n\n**Resend Request**: Use the state from the previous response to resend OTP to the same contact.\n\n**Rate Limiting**: \n- Maximum verification attempts per session (configurable, default: 5)\n- Maximum resend attempts per session (configurable, default: 5) \n- Minimum interval between resends (configurable, default: 30 seconds)\n\n**Supported Channels**: SMS, Email\n\n**Error Scenarios**:\n- `invalid_request`: Missing or invalid contact details, missing required fields\n- `invalid_state`: State is invalid, expired, or not found\n- `resends_not_allowed`: Resend attempted before the minimum interval\n- `resends_exhausted`: Maximum resend attempts reached for this session\n- `sms_service_error`: External SMS service failure\n- `email_service_error`: External email service failure\n- `internal_server_error`: General server error\n\n**Required Headers**: `tenant-id` header is mandatory for all requests.\n"
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1OtpSendRequestBody'
        required: true
      responses:
        '200':
          description: OTP sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1OtpSendResponse'
        '400':
          description: Bad Request - Various validation and rate limiting errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_request_missing_contact:
                  summary: Missing contact details
                  value:
                    error:
                      code: invalid_request
                      message: Invalid contact
                invalid_request_missing_channel:
                  summary: Missing channel in contact
                  value:
                    error:
                      code: invalid_request
                      message: Invalid contact
                invalid_request_missing_identifier:
                  summary: Missing identifier in contact
                  value:
                    error:
                      code: invalid_request
                      message: Invalid contact
                invalid_state:
                  summary: Invalid or expired state
                  value:
                    error:
                      code: invalid_state
                      message: Invalid state
                resend_not_allowed:
                  summary: Resend attempted too soon
                  value:
                    error:
                      code: resends_not_allowed
                      message: Resend triggered too quick, Try again later
                      metadata:
                        resendAfter: 1640995200
                resends_exhausted:
                  summary: Maximum resend attempts reached
                  value:
                    error:
                      code: resends_exhausted
                      message: Resends exhausted
        '500':
          description: Internal Server Error - Service failures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sms_service_error:
                  summary: SMS service failure
                  value:
                    error:
                      code: sms_service_error
                      message: SMS service error
                email_service_error:
                  summary: Email service failure
                  value:
                    error:
                      code: email_service_error
                      message: Email service error
                internal_server_error:
                  summary: General server error
                  value:
                    error:
                      code: internal_server_error
                      message: Something went wrong
  /v1/otp/verify:
    post:
      tags:
      - Passwordless
      summary: Verify OTP for contact verification
      description: 'API to verify the OTP sent to a contact. Use the state received from the send OTP API along with the OTP received by the user.


        **Verification Rules**:

        - OTP must be valid and not expired (configurable validity, default: 15 minutes)

        - Maximum verification attempts per session (configurable, default: 5)

        - State must be valid and not expired


        **Success**: Returns 204 No Content on successful verification


        **Error Scenarios**:

        - `invalid_request`: Missing state or OTP parameters

        - `invalid_state`: State is invalid, expired, or not found

        - `incorrect_otp`: OTP is incorrect (includes remaining retry count in metadata)

        - `retries_exhausted`: Maximum verification attempts reached for this session

        - `internal_server_error`: General server error


        **Required Headers**: `tenant-id` header is mandatory for all requests.


        **State Management**: After successful verification or when retries are exhausted, the state is automatically cleaned up and cannot be reused.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1OtpVerifyRequestBody'
        required: true
      responses:
        '204':
          description: OTP verified successfully
        '400':
          description: Bad Request - Validation errors, invalid OTP, invalid state, or retries exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_request_missing_state:
                  summary: Missing state parameter
                  value:
                    error:
                      code: invalid_request
                      message: State is missing
                invalid_request_missing_otp:
                  summary: Missing OTP parameter
                  value:
                    error:
                      code: invalid_request
                      message: OTP is missing
                invalid_state:
                  summary: Invalid or expired state
                  value:
                    error:
                      code: invalid_state
                      message: Invalid state
                incorrect_otp:
                  summary: Incorrect OTP provided
                  value:
                    error:
                      code: incorrect_otp
                      message: Incorrect otp
                      metadata:
                        retriesLeft: 3
                retries_exhausted:
                  summary: Maximum verification attempts reached
                  value:
                    error:
                      code: retries_exhausted
                      message: Retries exhausted
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    V1OtpVerifyRequestBody:
      type: object
      required:
      - state
      - otp
      properties:
        state:
          type: string
          description: State received from OTP send response
          example: abc123def456
        otp:
          type: string
          description: OTP received by the user
          example: '123456'
          minLength: 4
          maxLength: 8
    Template:
      type: object
      properties:
        name:
          type: string
          example: templateName
        params:
          type: object
          example:
            variable-1: value-1
            variable-2: value-2
    V2TokenResponse:
      type: object
      description: Token response for v2 endpoints (uses snake_case field names)
      properties:
        access_token:
          type: string
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
          description: Short lived Bearer JWT token to access APIs
        refresh_token:
          type: string
          example: refresh_token_xyz789
          description: Long lived token used to refresh access token
        id_token:
          type: string
          example: eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzAyNzg5...
          description: OpenID Connect ID token
        sso_token:
          type: string
          example: sso_token_abc123
          description: Single Sign-On token for session management
        token_type:
          type: string
          example: Bearer
          description: Type of token. Only supports Bearer for now
        expires_in:
          type: integer
          example: 3600
          description: Expiry of the access token in seconds
        is_new_user:
          type: boolean
          description: Indicates if the user is new
          example: false
    State:
      type: object
      properties:
        state:
          type: string
          example: accesstoken
        tries:
          type: number
          example: 1
        retriesLeft:
          type: number
          example: 4
        resends:
          type: number
          example: 1
        resendsLeft:
          type: number
          example: 4
        resendAfter:
          type: number
          example: 30
        isNewUser:
          type: boolean
          example: true
    V1PasswordlessCompleteRequestBody:
      type: object
      required:
      - state
      - otp
      properties:
        state:
          type: string
          example: state
        otp:
          type: string
          example: 123456
    MetaInfo:
      type: object
      properties:
        ip:
          type: string
        location:
          type: string
        device_name:
          type: string
        source:
          type: string
    V2PasswordlessInitResponse:
      type: object
      properties:
        tries:
          type: integer
          description: Number of verification attempts made
          example: 1
        retries_left:
          type: integer
          description: Number of verification attempts remaining
          example: 4
        resends:
          type: integer
          description: Number of times OTP has been resent
          example: 1
        resends_left:
          type: integer
          description: Number of resends remaining
          example: 4
        resend_after:
          type: integer
          description: Unix timestamp after which resend is allowed
          example: 1640995230
        is_new_user:
          type: boolean
          description: Whether this is a new user
          example: false
        state:
          type: string
          description: State token for subsequent requests
          example: state
    V1OtpSendRequestBody:
      type: object
      description: Request body for sending OTP. Either provide contact details for first request or state for resend.
      properties:
        state:
          type: string
          description: State from previous OTP send response (used for resending OTP)
          example: abc123def456
        contact:
          $ref: '#/components/schemas/Contact'
      oneOf:
      - required:
        - contact
      - required:
        - state
      example:
        contact:
          channel: sms
          identifier: '9999999999'
    V2PasswordlessInitRequestBody:
      type: object
      required:
      - client_id
      - contacts
      properties:
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
        state:
          type: string
          description: State from previous request (for resend)
          example: state
        response_type:
          type: string
          description: Desired response type
          enum:
          - code
          - token
          example: token
        contacts:
          type: array
          description: List of contacts (email or phone) to send OTP to
          items:
            $ref: '#/components/schemas/Contact'
          minItems: 1
        scopes:
          type: array
          description: List of scopes to request
          items:
            type: string
          example:
          - openid
          - email
          - profile
        flow:
          type: string
          description: Authentication flow type
          enum:
          - signinup
          - signin
          - signup
          default: signinup
          example: signinup
        meta_info:
          $ref: '#/components/schemas/MetaInfo'
    Contact:
      type: object
      required:
      - channel
      - identifier
      properties:
        channel:
          type: string
          description: Contact channel
          enum:
          - sms
          - email
          example: sms
        identifier:
          type: string
          description: Phone number (SMS) or email address (email)
          example: '9999999999'
        template:
          $ref: '#/components/schemas/Template'
          description: Template override (uses tenant default if not provided)
    V1OtpSendResponse:
      type: object
      description: Response after sending OTP with rate limiting information
      properties:
        state:
          type: string
          description: Unique state identifier for this OTP session
          example: abc123def456
        tries:
          type: integer
          description: Number of verification attempts made so far
          example: 0
          minimum: 0
        retriesLeft:
          type: integer
          description: Number of verification attempts remaining
          example: 5
          minimum: 0
        resends:
          type: integer
          description: Number of resend attempts made so far
          example: 1
          minimum: 0
        resendsLeft:
          type: integer
          description: Number of resend attempts remaining
          example: 4
          minimum: 0
        resendAfter:
          type: integer
          format: int64
          description: Seconds to wait before next resend is allowed
          example: 30
          minimum: 0
    V1PasswordlessInitRequestBody:
      type: object
      properties:
        state:
          type: string
          example: state
        flow:
          type: string
          example: signin
        responseType:
          type: string
          example: token
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        metaInfo:
          $ref: '#/components/schemas/MetaInfo'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: invalid_request
            message:
              type: string
              description: Human-readable error message
              example: Something went wrong.
    TokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          example: accesstoken
          description: Short lived Bearer JWT token to access APIs.
        refreshToken:
          type: string
          example: refreshToken
          description: Long Lived token used to refresh access token.
        idToken:
          type: string
          example: idToken
          description: OpenID Connect ID token
        tokenType:
          type: string
          example: Bearer
          description: type of token. Only supports Bearer for now.
        expiresIn:
          type: integer
          example: 3600
          description: expiry of the access token in seconds
        isNewUser:
          type: boolean
          description: Indicates if the user is new
          example: false
  parameters:
    TenantIdHeader:
      name: tenant-id
      in: header
      description: tenant-id of the client integrating with guardian
      required: true
      schema:
        type: string