Dream Sports Session Management API

openapi: 3.2.0
info:
  title: Guardian Session Management API
  version: 1.0.0
tags:
- name: Session Management
paths:
  /v1/refreshToken:
    post:
      tags:
      - Session Management
      summary: API to get a new access token using the refresh token
      description: 'API to get a new access token using the refresh token.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1RefreshTokenRequestBody'
        required: true
      responses:
        '200':
          description: User is successfully signed up
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RefreshToken'
        '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/logout:
    post:
      tags:
      - Session Management
      summary: User logout
      description: 'Log out a user by invalidating their refresh token and clearing session cookies.


        **Logout Types:**

        - **Standard Logout**: Invalidates only the provided refresh token

        - **Universal Logout**: If `isUniversalLogout` is true, invalidates all refresh tokens for the user


        **Behavior:**

        - Validates the provided refresh token

        - Invalidates the token(s) based on logout type

        - Clears authentication cookies by setting them to null

        - Returns 204 No Content on success


        **Request Body:**

        - `refreshToken` (required): The refresh token to invalidate

        - `isUniversalLogout` (optional): Whether to invalidate all user sessions (default: false)

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1LogoutRequestBody'
        required: true
      responses:
        '204':
          description: User successfully logged out
          headers:
            Set-Cookie:
              description: Clears authentication cookies (access token and refresh token)
              schema:
                type: array
                items:
                  type: string
                example:
                - AT=; Path=/; Domain=example.com; Max-Age=0; HttpOnly; Secure; SameSite=Strict
                - RT=; Path=/; Domain=example.com; Max-Age=0; HttpOnly; Secure; SameSite=Strict
        '400':
          description: Bad Request due to missing or invalid refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_refresh_token:
                  summary: Missing refresh token
                  value:
                    error:
                      code: invalid_request
                      message: Refresh token is required
                invalid_refresh_token:
                  summary: Invalid refresh token
                  value:
                    error:
                      code: unauthorized
                      message: Invalid refresh token
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/refresh-token:
    post:
      tags:
      - Session Management
      summary: API to get a new access token using the refresh token
      description: 'API to get a new access token using the refresh token. The refresh token can be provided in the request body or as a cookie.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2RefreshTokenRequestBody'
        required: false
      responses:
        '200':
          description: Access token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2RefreshTokenResponse'
          headers:
            Set-Cookie:
              description: Sets the access token cookie
              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'
        '401':
          description: Unauthorized - Invalid refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Set-Cookie:
              description: Clears authentication cookies (access token and refresh token)
              schema:
                type: array
                items:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/logout:
    post:
      tags:
      - Session Management
      summary: User logout
      description: 'Log out a user by invalidating their refresh token and clearing session cookies.


        **Logout Types:**

        - **Token Logout**: Invalidates only the provided refresh token (default)

        - **Client Logout**: If `logout_type` is set to `client`, invalidates all refresh tokens for the user for the specific client

        - **Tenant Logout**: If `logout_type` is set to `tenant`, invalidates all refresh tokens for the user for the tenant (requires first-party client)


        **Behavior:**

        - Validates the provided refresh token (can be in request body or cookie)

        - Invalidates the token(s) based on logout type

        - Clears authentication cookies by setting them to null

        - Returns 204 No Content on success


        **Request Body:**

        - `refresh_token` (optional): The refresh token to invalidate (can also be provided as cookie)

        - `logout_type` (optional): Type of logout - `token` (default), `client`, or `tenant`

        - `client_id` (optional): Client ID for the logout operation

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2LogoutRequestBody'
        required: false
      responses:
        '204':
          description: User successfully logged out
          headers:
            Set-Cookie:
              description: Clears authentication cookies (access token, refresh token, and SSO token)
              schema:
                type: array
                items:
                  type: string
                example:
                - AT=; Path=/; Domain=example.com; Max-Age=0; HttpOnly; Secure; SameSite=Strict
                - RT=; Path=/; Domain=example.com; Max-Age=0; HttpOnly; Secure; SameSite=Strict
                - SSO=; Path=/; Domain=example.com; Max-Age=0; HttpOnly; Secure; SameSite=Strict
        '400':
          description: Bad Request due to missing or invalid refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_refresh_token:
                  summary: Missing refresh token
                  value:
                    error:
                      code: invalid_request
                      message: Refresh token is required
                invalid_refresh_token:
                  summary: Invalid refresh token
                  value:
                    error:
                      code: unauthorized
                      message: Invalid refresh token
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/user/refresh-tokens:
    get:
      tags:
      - Session Management
      summary: Get user's active refresh tokens
      description: 'Returns a paginated list of active refresh tokens for the authenticated user and client.

        The user is identified from the Bearer access token; client_id must match the token''s client.


        **Authentication:**

        - Requires a valid Bearer access token in the Authorization header


        **Query parameters:**

        - `client_id` (required): Client ID; must match the client_id in the access token

        - `page` (optional): Page number (1-based). Default 1

        - `page_size` (optional): Number of items per page (1-100). Default 10


        **Response:**

        - `refresh_tokens`: List of active refresh tokens with device/location metadata

        - `total_count`: Total number of active refresh tokens (across all pages)

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: Authorization
        in: header
        required: true
        description: Bearer access token
        schema:
          type: string
          example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
      - name: client_id
        in: query
        required: true
        description: Client ID (must match the access token's client_id)
        schema:
          type: string
          example: my-client-id
      - name: page
        in: query
        required: false
        description: Page number (1-based). Default 1
        schema:
          type: integer
          minimum: 1
          default: 1
          example: 1
      - name: page_size
        in: query
        required: false
        description: Number of items per page (1-100). Default 10
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          example: 10
      responses:
        '200':
          description: List of active refresh tokens retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRefreshTokensResponse'
        '400':
          description: Bad Request (e.g. missing client_id, invalid page or page_size)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (invalid/expired token or client_id mismatch)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            WWW-Authenticate:
              description: Bearer error details
              schema:
                type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    V2RefreshTokenRequestBody:
      type: object
      properties:
        refresh_token:
          type: string
          description: Refresh token (can also be provided as cookie)
          example: refresh_token_xyz789
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
    UserRefreshTokenItem:
      type: object
      description: A single active refresh token with device/location metadata
      properties:
        refresh_token:
          type: string
          description: The refresh token value
        device_name:
          type: string
          description: Device name associated with the token
        location:
          type: string
          description: Location when the token was created
        ip:
          type: string
          description: IP address when the token was created
        source:
          type: string
          description: Source (e.g. mobile, web)
        created_at:
          type: string
          description: When the refresh token was created (format yyyy-MM-dd HH:mm:ss)
          example: '2022-09-30 12:25:26'
    V2RefreshTokenResponse:
      type: object
      required:
      - access_token
      - token_type
      - expires_in
      properties:
        access_token:
          type: string
          description: New access token
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        token_type:
          type: string
          description: Token type
          enum:
          - Bearer
          example: Bearer
        expires_in:
          type: integer
          description: Access token expiration time in seconds
          example: 3600
    RefreshToken:
      type: object
      properties:
        accessToken:
          type: string
          example: accesstoken
          description: Short lived Bearer JWT token to access APIs.
        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
    UserRefreshTokensResponse:
      type: object
      description: Paginated list of user's active refresh tokens
      required:
      - refresh_tokens
      - total_count
      properties:
        refresh_tokens:
          type: array
          description: List of active refresh tokens for the current page
          items:
            $ref: '#/components/schemas/UserRefreshTokenItem'
        total_count:
          type: integer
          format: int64
          description: Total number of active refresh tokens (across all pages)
      example:
        refresh_tokens:
        - refresh_token: abc123...
          device_name: iPhone 13
          location: New York, USA
          ip: 192.168.1.1
          source: mobile
          created_at: '2022-09-30 12:25:26'
        - refresh_token: def456...
          device_name: MacBook Pro
          location: San Francisco, USA
          ip: 10.0.0.1
          source: web
          created_at: '2022-09-29 14:20:00'
        total_count: 2
    V2LogoutRequestBody:
      type: object
      properties:
        refresh_token:
          type: string
          description: Refresh token to invalidate (can also be provided as cookie)
          example: refresh_token_xyz789
        logout_type:
          type: string
          description: Type of logout
          enum:
          - token
          - client
          - tenant
          default: token
          example: token
        client_id:
          type: string
          description: Client identifier
          example: my-client-id
    V1RefreshTokenRequestBody:
      type: object
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
    V1LogoutRequestBody:
      type: object
      required:
      - refreshToken
      properties:
        refreshToken:
          type: string
        isUniversalLogout:
          type: boolean
          default: false
    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.
  parameters:
    TenantIdHeader:
      name: tenant-id
      in: header
      description: tenant-id of the client integrating with guardian
      required: true
      schema:
        type: string