Dream Sports Social API

openapi: 3.2.0
info:
  title: Guardian Social API
  version: 1.0.0
tags:
- name: Social
paths:
  /v1/auth/fb:
    post:
      tags:
      - Social
      summary: Signin, Signup or Signinup using the facebook access_token
      description: 'API to signin, signup or signinup using the facebook access_token. The access_token is verified via the https://graph.facebook.com/me endpoint.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1AuthFbRequestBody'
        required: true
      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 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/auth/google:
    post:
      tags:
      - Social
      summary: Signin, Signup or Signinup user using ID token verification.
      description: 'API to signin, signup or signinup a user using Google issued ID token.


        The id token is verified statelessly via the public keys exposed by Google using the JWKS URI.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1AuthGoogleRequestBody'
        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/idp/connect:
    post:
      tags:
      - Social
      summary: Connect to external identity provider
      description: 'Establish a connection with an external identity provider for authentication.


        This endpoint allows Guardian to connect to external identity providers

        (IdPs) for user authentication and profile information retrieval.


        **Configuration Requirements:**

        - Provider-specific client credentials (client ID and secret)

        - Redirect URI for OAuth flows

        - Optional scope and endpoint configuration

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        description: Identity provider connection request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdpConnectRequestBody'
        required: true
      responses:
        '200':
          description: IdP authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdpConnectResponse'
        '400':
          description: Bad Request due to missing parameters, invalid configuration, or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_provider:
                  summary: Missing provider field
                  value:
                    error:
                      code: invalid_request
                      message: Provider is required
                invalid_provider:
                  summary: Invalid provider name
                  value:
                    error:
                      code: invalid_request
                      message: 'Provider must be one of: google, facebook, oidc'
                missing_credentials:
                  summary: Missing credentials
                  value:
                    error:
                      code: invalid_request
                      message: Credentials are required
                invalid_redirect_uri:
                  summary: Invalid redirect URI
                  value:
                    error:
                      code: invalid_request
                      message: Invalid redirect URI format
                missing_endpoints:
                  summary: Missing endpoints for OIDC provider
                  value:
                    error:
                      code: invalid_request
                      message: Endpoints configuration is required for OIDC providers
        '401':
          description: Unauthorized - Invalid tenant or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_tenant:
                  summary: Invalid tenant ID
                  value:
                    error:
                      code: unauthorized
                      message: Invalid tenant-id header
        '409':
          description: Conflict - Connection already exists for this provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                connection_exists:
                  summary: Provider connection already exists
                  value:
                    error:
                      code: conflict
                      message: A connection for this provider already exists
                      metadata:
                        existingConnectionId: conn_google_existing123
        '422':
          description: Unprocessable Entity - Provider validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                provider_validation_failed:
                  summary: Failed to validate provider credentials
                  value:
                    error:
                      code: provider_validation_failed
                      message: Unable to validate provider credentials
                invalid_client_credentials:
                  summary: Invalid client credentials
                  value:
                    error:
                      code: invalid_client_credentials
                      message: Provider rejected the client credentials
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/auth/fb:
    post:
      tags:
      - Social
      summary: Signin, Signup or Signinup using the facebook access_token
      description: 'API to signin, signup or signinup using the facebook access_token. The access_token is verified via the https://graph.facebook.com/me endpoint.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2AuthFbRequestBody'
        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 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/auth/google:
    post:
      tags:
      - Social
      summary: Signin, Signup or Signinup user using ID token verification.
      description: 'API to signin, signup or signinup a user using Google issued ID token.


        The id token is verified statelessly via the public keys exposed by Google using the JWKS URI.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2AuthGoogleRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully signed 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'
  /v2/idp/connect:
    post:
      tags:
      - Social
      summary: Connect to external identity provider
      description: 'Establish a connection with an external identity provider for authentication.


        This endpoint allows Guardian to connect to external identity providers

        (IdPs) for user authentication and profile information retrieval.


        **Configuration Requirements:**

        - Provider-specific client credentials (client ID and secret)

        - Redirect URI for OAuth flows

        - Optional scope and endpoint configuration

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        description: Identity provider connection request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2IdpConnectRequestBody'
        required: true
      responses:
        '200':
          description: IdP authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2IdpConnectResponse'
          headers:
            Set-Cookie:
              description: Sets authentication cookies when tokens are returned (access token, refresh token)
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Bad Request due to missing parameters, invalid configuration, or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_provider:
                  summary: Missing provider field
                  value:
                    error:
                      code: invalid_request
                      message: Provider is required
                invalid_provider:
                  summary: Invalid provider name
                  value:
                    error:
                      code: invalid_request
                      message: 'Provider must be one of: google, facebook, oidc'
                missing_credentials:
                  summary: Missing credentials
                  value:
                    error:
                      code: invalid_request
                      message: Credentials are required
                invalid_redirect_uri:
                  summary: Invalid redirect URI
                  value:
                    error:
                      code: invalid_request
                      message: Invalid redirect URI format
                missing_endpoints:
                  summary: Missing endpoints for OIDC provider
                  value:
                    error:
                      code: invalid_request
                      message: Endpoints configuration is required for OIDC providers
        '401':
          description: Unauthorized - Invalid tenant or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_tenant:
                  summary: Invalid tenant ID
                  value:
                    error:
                      code: unauthorized
                      message: Invalid tenant-id header
        '409':
          description: Conflict - Connection already exists for this provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                connection_exists:
                  summary: Provider connection already exists
                  value:
                    error:
                      code: conflict
                      message: A connection for this provider already exists
                      metadata:
                        existingConnectionId: conn_google_existing123
        '422':
          description: Unprocessable Entity - Provider validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                provider_validation_failed:
                  summary: Failed to validate provider credentials
                  value:
                    error:
                      code: provider_validation_failed
                      message: Unable to validate provider credentials
                invalid_client_credentials:
                  summary: Invalid client credentials
                  value:
                    error:
                      code: invalid_client_credentials
                      message: Provider rejected the client credentials
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      code: internal_server_error
                      message: An unexpected error occurred while establishing the connection
components:
  schemas:
    V2AuthFbRequestBody:
      type: object
      required:
      - client_id
      - access_token
      - response_type
      properties:
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
        access_token:
          type: string
          description: Facebook access token
          example: EAABwzLixnjYBO...
        response_type:
          type: string
          description: Desired response type
          enum:
          - code
          - token
          example: token
        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'
    V1AuthGoogleRequestBody:
      type: object
      properties:
        idToken:
          type: string
        responseType:
          type: string
        flow:
          type: string
        metaInfo:
          $ref: '#/components/schemas/MetaInfo'
    V2IdpConnectResponse:
      type: object
      description: Response from identity provider authentication (v2 - uses snake_case field names)
      properties:
        code:
          type: string
          description: Authorization code (present when response_type is 'code')
          example: 4/0AX4XfWjY1Z2X3Y4Z5A6B7C8D9E0F1G2H3I4J5K6L7M8N9O0P1Q2R3S4T5U6V7W8X9Y0Z1
        access_token:
          type: string
          description: Access token (present when response_type is 'token')
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        refresh_token:
          type: string
          description: Refresh token for getting new access tokens
          example: 1//04xxxxxxxxxxxxx-refreshtoken
        id_token:
          type: string
          description: OpenID Connect ID token
          example: eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzAyNzg5...
        token_type:
          type: string
          description: Type of the access token
          example: Bearer
        expires_in:
          type: integer
          description: Access token expiration time in seconds
          example: 3600
        is_new_user:
          type: boolean
          description: Whether this is a newly created user
          example: false
        idp_credentials:
          type: object
          description: Identity provider specific credentials
          properties:
            access_token:
              type: string
              description: Provider's access token
              example: ya29.a0AfH6SMC...
            refresh_token:
              type: string
              description: Provider's refresh token
              example: 1//04xxxxxxxxxxxxx
            id_token:
              type: string
              description: Provider's ID token
              example: eyJhbGciOiJSUzI1NiIsImtpZCI6...
    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
    V2AuthGoogleRequestBody:
      type: object
      required:
      - client_id
      - id_token
      - response_type
      properties:
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
        id_token:
          type: string
          description: Google issued ID token
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        response_type:
          type: string
          description: Desired response type
          enum:
          - code
          - token
          example: token
        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'
    MetaInfo:
      type: object
      properties:
        ip:
          type: string
        location:
          type: string
        device_name:
          type: string
        source:
          type: string
    V1AuthFbRequestBody:
      type: object
      properties:
        accessToken:
          type: string
        responseType:
          type: string
        flow:
          type: string
        metaInfo:
          $ref: '#/components/schemas/MetaInfo'
    V2IdpConnectRequestBody:
      type: object
      description: Request body for connecting to external identity providers (v2)
      required:
      - client_id
      - id_provider
      - identifier
      - identifier_type
      - response_type
      properties:
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
        id_provider:
          type: string
          description: Identity provider name (configured provider identifier)
          example: google
        identifier:
          type: string
          description: 'Provider-specific identifier for authentication:

            - For authorization code flow: the authorization code

            - For ID token flow: the ID token

            '
          example: 4/0AX4XfWjY1Z2X3Y4Z5...
        identifier_type:
          type: string
          description: Type of identifier being provided
          enum:
          - code
          - id_token
          example: code
        response_type:
          type: string
          description: Desired response type for the authentication flow
          enum:
          - code
          - token
          example: token
        nonce:
          type: string
          description: Optional nonce value for OIDC flows
          example: abc123nonce
        code_verifier:
          type: string
          description: PKCE code verifier for authorization code flow
          example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
        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'
    IdpConnectResponse:
      type: object
      description: Response from identity provider authentication
      properties:
        code:
          type: string
          description: Authorization code (present when responseType is 'code')
          example: 4/0AX4XfWjY1Z2X3Y4Z5A6B7C8D9E0F1G2H3I4J5K6L7M8N9O0P1Q2R3S4T5U6V7W8X9Y0Z1
        accessToken:
          type: string
          description: Access token (present when responseType is 'token')
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        refreshToken:
          type: string
          description: Refresh token for getting new access tokens
          example: 1//04xxxxxxxxxxxxx-refreshtoken
        idToken:
          type: string
          description: OpenID Connect ID token
          example: eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzAyNzg5...
        tokenType:
          type: string
          description: Type of the access token
          example: Bearer
        expiresIn:
          type: integer
          description: Access token expiration time in seconds
          example: 3600
        isNewUser:
          type: boolean
          description: Whether this is a newly created user
          example: false
        idpCredentials:
          type: object
          description: Identity provider specific credentials
          properties:
            accessToken:
              type: string
              description: Provider's access token
              example: ya29.a0AfH6SMC...
            refreshToken:
              type: string
              description: Provider's refresh token
              example: 1//04xxxxxxxxxxxxx
            idToken:
              type: string
              description: Provider's ID token
              example: eyJhbGciOiJSUzI1NiIsImtpZCI6...
    IdpConnectRequestBody:
      type: object
      description: Request body for connecting to external identity providers
      required:
      - idProvider
      - identifier
      - responseType
      properties:
        idProvider:
          type: string
          description: Identity provider name (configured provider identifier)
          example: google
        identifier:
          type: string
          description: 'Provider-specific identifier for authentication:

            - For authorization code flow: the authorization code

            - For ID token flow: the ID token

            '
          example: 4/0AX4XfWjY1Z2X3Y4Z5...
        identifierType:
          type: string
          description: Type of identifier being provided
          enum:
          - code
          - id_token
          default: code
          example: code
        responseType:
          type: string
          description: Desired response type for the authentication flow
          enum:
          - code
          - token
          example: token
        nonce:
          type: string
          description: Optional nonce value for OIDC flows
          example: abc123nonce
        codeVerifier:
          type: string
          description: PKCE code verifier for authorization code flow
          example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
        flow:
          type: string
          description: Authentication flow type
          enum:
          - signinup
          - signin
          - signup
          default: signinup
          example: signinup
        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