Dream Sports Password API

openapi: 3.2.0
info:
  title: Guardian Password API
  version: 1.0.0
tags:
- name: Password
paths:
  /v2/signin:
    post:
      tags:
      - Password
      summary: Sign in using user identifier with password or PIN
      description: "Authenticates a user using a user identifier (username, email, or phone number) with either\npassword or PIN. Supports both token and code response types. On success, returns tokens\nand optionally sets authentication cookies.\n\n**Authentication methods:**\n- **Password:** Provide `password` with user identifier. Uses client's post authenticate\n  user API for validation.\n- **PIN:** Provide `pin` with user identifier for PIN/pattern authentication.\n\n**Response types:**\n- `token`: Returns access_token, refresh_token, id_token, sso_token in response body and\n  optionally as Set-Cookie headers.\n- `code`: Returns authorization code for OAuth code flow.\n\n**User flow block:** After too many failed attempts, the user's flow may be blocked. A 403\nresponse with `error.code: \"flow_blocked\"` indicates the block. Use `metadata.retryAfter`\n(Unix timestamp) to know when the block expires. To manage blocks, see:\n- `POST /v1/user/flow/block` - Block a user's flow\n- `POST /v1/user/flow/unblock` - Unblock a user's flow\n- `GET /v1/user/flow/blocked` - Check if a user's flow is blocked\n"
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2SignInUpRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully signed in
          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, invalid data, or missing config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                password_pin_block_not_configured:
                  summary: Password pin block not configured
                  value:
                    error:
                      code: password_pin_block_not_configured
                      message: Password pin block is not configured
        '403':
          description: Forbidden - User's flow is blocked due to too many failed attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                flow_blocked:
                  summary: User flow blocked
                  value:
                    error:
                      code: flow_blocked
                      message: Too many failed attempts. Please try again later.
                      metadata:
                        retryAfter: 1640995230
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/signup:
    post:
      tags:
      - Password
      summary: Signup a new user using username and password
      description: 'API to sign up a new user using username and password.


        If the username already exists, the API will return a failure, otherwise a new user is created with the given username and password.


        This API uses the clients get user API to ascertain if the username exists or not.


        This API uses the clients post user API to create a new user account with the provided credentials.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1SignupRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully signed 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'
  /v1/signin:
    post:
      tags:
      - Password
      summary: Signin existing user using username and password
      description: 'This API signs in an existing user using username and password.


        This API uses the clients post authenticate user API to validate if the username password combination is correct.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1SigninRequestBody'
      responses:
        '200':
          description: User is successfully signed in
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad Request due to missing parameters, invalid data, or missing config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                password_pin_block_not_configured:
                  summary: Password pin block not configured
                  value:
                    error:
                      code: password_pin_block_not_configured
                      message: Password pin block is not configured
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    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
    V1SignupRequestBody:
      type: object
      properties:
        username:
          type: string
          example: JohnTheMan
        password:
          type: string
          example: wordpass@1234
        responseType:
          type: string
          example: token
        metaInfo:
          $ref: '#/components/schemas/MetaInfo'
    MetaInfo:
      type: object
      properties:
        ip:
          type: string
        location:
          type: string
        device_name:
          type: string
        source:
          type: string
    V2SignInUpRequestBody:
      type: object
      required:
      - client_id
      - response_type
      description: 'Exactly one of username, email, or phone_number is required.

        Exactly one of password or pin is required.

        '
      properties:
        username:
          type: string
          description: User identifier (username)
          example: JohnTheMan
        email:
          type: string
          description: User identifier (email)
          example: user@example.com
        phone_number:
          type: string
          description: User identifier (phone number)
          example: '+1234567890'
        password:
          type: string
          description: Password for authentication (use with password flow)
          example: wordpass@1234
        pin:
          type: string
          description: PIN for authentication (use with PIN flow)
          example: '1234'
        response_type:
          type: string
          description: Desired response type
          enum:
          - code
          - token
          example: token
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
        scopes:
          type: array
          description: List of scopes to request
          items:
            type: string
          example:
          - openid
          - email
          - profile
        meta_info:
          $ref: '#/components/schemas/MetaInfo'
    V1SigninRequestBody:
      type: object
      properties:
        username:
          type: string
          example: JohnTheMan
        password:
          type: string
          example: wordpass@1234
        responseType:
          type: string
          example: token
        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