Dream Sports OIDC Client Management API

openapi: 3.2.0
info:
  title: Guardian OIDC Client Management API
  version: 1.0.0
tags:
- name: OIDC Client Management
paths:
  /v1/admin/client:
    post:
      tags:
      - OIDC Client Management
      summary: Create a new OAuth 2.0 client
      description: 'Create a new OAuth 2.0 client for the tenant. This endpoint allows administrators

        to register new applications that can use the OAuth 2.0 and OpenID Connect flows.


        **Client Configuration:**

        - Each client must have a unique client name within the tenant

        - Grant types determine which OAuth 2.0 flows the client can use

        - Response types define the authorization flows supported

        - Redirect URIs must be pre-registered for security

        - Skip consent option allows bypassing user consent for trusted applications


        **Security Considerations:**

        - Client secrets are automatically generated and should be kept secure

        - Redirect URIs are validated to prevent open redirect attacks

        - Grant types and response types are validated against OAuth 2.0 specifications

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClientRequestBody'
        required: true
      responses:
        '201':
          description: Client created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '400':
          description: Bad Request due to missing parameters or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Client already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - OIDC Client Management
      summary: List OAuth 2.0 clients
      description: 'Retrieve a paginated list of OAuth 2.0 clients for the tenant.


        **Pagination:**

        - Page numbers start from 1

        - Page size can be between 1 and 100 (default: 10)

        - Results are ordered by creation date (newest first)


        **Response:**

        - Returns a list of client objects with basic information

        - Client secrets are not included in the response for security

        - Total count and pagination metadata are included

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          minimum: 1
          default: 1
          example: 1
      - name: page_size
        in: query
        required: false
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          example: 10
      responses:
        '200':
          description: Successfully retrieved clients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientListResponse'
        '400':
          description: Bad Request due to invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/admin/client/{client_id}:
    get:
      tags:
      - OIDC Client Management
      summary: Get OAuth 2.0 client details
      description: 'Retrieve detailed information about a specific OAuth 2.0 client.


        **Response:**

        - Returns complete client configuration including client secret

        - All registered redirect URIs, grant types, and response types

        - Contact information and policy URIs

        - Skip consent configuration


        **Security Note:** Client secrets are included in the response and should be handled securely.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: client_id
        in: path
        required: true
        description: Unique identifier of the client
        schema:
          type: string
          example: my-client-id
      responses:
        '200':
          description: Client details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - OIDC Client Management
      summary: Update OAuth 2.0 client
      description: 'Update an existing OAuth 2.0 client configuration. Only provided fields will be updated.


        **Update Rules:**

        - All fields are optional (partial updates supported)

        - Grant types and response types cannot be empty if provided

        - Redirect URIs cannot be empty if provided

        - Client name cannot be blank if provided


        **Security:**

        - Client secrets are not updated through this endpoint

        - Use the regenerate secret endpoint to update client secrets

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: client_id
        in: path
        required: true
        description: Unique identifier of the client
        schema:
          type: string
          example: my-client-id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClientRequestBody'
        required: true
      responses:
        '200':
          description: Client updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '400':
          description: Bad Request due to invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - OIDC Client Management
      summary: Delete OAuth 2.0 client
      description: 'Delete an OAuth 2.0 client and all its associated data.


        **Important:** This operation is irreversible and will:

        - Remove all client configurations

        - Delete all associated client scopes

        - Invalidate any existing tokens issued to this client


        **Security:** Ensure no active applications are using this client before deletion.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: client_id
        in: path
        required: true
        description: Unique identifier of the client
        schema:
          type: string
          example: my-client-id
      responses:
        '204':
          description: Client deleted successfully
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/admin/client/{client_id}/regenerate-secret:
    post:
      tags:
      - OIDC Client Management
      summary: Regenerate client secret
      description: 'Generate a new client secret for an existing OAuth 2.0 client.


        **Security Impact:**

        - The old client secret becomes invalid immediately

        - Any existing access tokens remain valid until expiration

        - Applications using this client will need to update their configuration


        **Response:**

        - Returns the new client secret

        - Store this securely as it won''t be shown again

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: client_id
        in: path
        required: true
        description: Unique identifier of the client
        schema:
          type: string
          example: my-client-id
      responses:
        '200':
          description: Client secret regenerated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientSecretResponse'
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ClientResponse:
      type: object
      description: OAuth 2.0 client response
      required:
      - client_id
      - client_name
      - grant_types
      - redirect_uris
      - response_types
      properties:
        client_id:
          type: string
          description: Unique identifier for the client
          example: my-client-id
        client_name:
          type: string
          description: Human-readable name for the client
          example: My Application
        client_secret:
          type: string
          description: Client secret (only shown on creation and regeneration)
          example: client_secret_xyz789
        client_uri:
          type: string
          format: uri
          description: URL of the client's home page
          example: https://myapp.com
        contacts:
          type: array
          description: List of contact email addresses
          items:
            type: string
            format: email
          example:
          - admin@myapp.com
        grant_types:
          type: array
          description: OAuth 2.0 grant types supported by the client
          items:
            type: string
            enum:
            - authorization_code
            - client_credentials
            - refresh_token
          example:
          - authorization_code
          - refresh_token
        logo_uri:
          type: string
          format: uri
          description: URL of the client's logo
          example: https://myapp.com/logo.png
        policy_uri:
          type: string
          format: uri
          description: URL of the client's privacy policy
          example: https://myapp.com/privacy
        redirect_uris:
          type: array
          description: List of authorized redirect URIs
          items:
            type: string
            format: uri
          example:
          - https://myapp.com/callback
        response_types:
          type: array
          description: OAuth 2.0 response types supported by the client
          items:
            type: string
            enum:
            - code
          example:
          - code
        skip_consent:
          type: boolean
          description: Whether to skip user consent for this client
          example: false
      example:
        client_id: my-client-id
        client_name: My Application
        client_secret: client_secret_xyz789
        client_uri: https://myapp.com
        contacts:
        - admin@myapp.com
        grant_types:
        - authorization_code
        - refresh_token
        redirect_uris:
        - https://myapp.com/callback
        response_types:
        - code
        skip_consent: false
    UpdateClientRequestBody:
      type: object
      description: Request body for updating an OAuth 2.0 client
      properties:
        client_name:
          type: string
          description: Human-readable name for the client
          example: My Updated Application
        client_uri:
          type: string
          format: uri
          description: URL of the client's home page
          example: https://myapp.com
        contacts:
          type: array
          description: List of contact email addresses
          items:
            type: string
            format: email
          example:
          - admin@myapp.com
          - support@myapp.com
        grant_types:
          type: array
          description: OAuth 2.0 grant types supported by the client
          items:
            type: string
            enum:
            - authorization_code
            - client_credentials
            - refresh_token
          example:
          - authorization_code
          - refresh_token
        logo_uri:
          type: string
          format: uri
          description: URL of the client's logo
          example: https://myapp.com/logo.png
        policy_uri:
          type: string
          format: uri
          description: URL of the client's privacy policy
          example: https://myapp.com/privacy
        redirect_uris:
          type: array
          description: List of authorized redirect URIs
          items:
            type: string
            format: uri
          example:
          - https://myapp.com/callback
          - https://myapp.com/silent-renew
        response_types:
          type: array
          description: OAuth 2.0 response types supported by the client
          items:
            type: string
            enum:
            - code
          example:
          - code
        skip_consent:
          type: boolean
          description: Whether to skip user consent for this client
          example: false
      example:
        client_name: My Updated Application
        client_uri: https://myapp.com
        grant_types:
        - authorization_code
        - refresh_token
        redirect_uris:
        - https://myapp.com/callback
        response_types:
        - code
    ClientListResponse:
      type: object
      description: Paginated list of OAuth 2.0 clients
      required:
      - clients
      - page
      - page_size
      properties:
        clients:
          type: array
          description: List of client objects
          items:
            $ref: '#/components/schemas/ClientResponse'
        page:
          type: integer
          description: Current page number
          example: 1
        page_size:
          type: integer
          description: Number of items per page
          example: 10
      example:
        clients:
        - client_id: client-1
          client_name: First Application
          grant_types:
          - authorization_code
          redirect_uris:
          - https://app1.com/callback
          response_types:
          - code
          skip_consent: false
        - client_id: client-2
          client_name: Second Application
          grant_types:
          - authorization_code
          - refresh_token
          redirect_uris:
          - https://app2.com/callback
          response_types:
          - code
          skip_consent: true
        page: 1
        page_size: 10
    CreateClientRequestBody:
      type: object
      description: Request body for creating a new OAuth 2.0 client
      required:
      - client_name
      - grant_types
      - redirect_uris
      - response_types
      properties:
        client_name:
          type: string
          description: Human-readable name for the client
          example: My Application
        client_uri:
          type: string
          format: uri
          description: URL of the client's home page
          example: https://myapp.com
        contacts:
          type: array
          description: List of contact email addresses
          items:
            type: string
            format: email
          example:
          - admin@myapp.com
          - support@myapp.com
        grant_types:
          type: array
          description: OAuth 2.0 grant types supported by the client
          items:
            type: string
            enum:
            - authorization_code
            - client_credentials
            - refresh_token
          example:
          - authorization_code
          - refresh_token
        logo_uri:
          type: string
          format: uri
          description: URL of the client's logo
          example: https://myapp.com/logo.png
        policy_uri:
          type: string
          format: uri
          description: URL of the client's privacy policy
          example: https://myapp.com/privacy
        redirect_uris:
          type: array
          description: List of authorized redirect URIs
          items:
            type: string
            format: uri
          example:
          - https://myapp.com/callback
          - https://myapp.com/silent-renew
        response_types:
          type: array
          description: OAuth 2.0 response types supported by the client
          items:
            type: string
            enum:
            - code
          example:
          - code
        skip_consent:
          type: boolean
          description: Whether to skip user consent for this client
          default: false
          example: false
      example:
        client_name: My Application
        client_uri: https://myapp.com
        contacts:
        - admin@myapp.com
        grant_types:
        - authorization_code
        - refresh_token
        redirect_uris:
        - https://myapp.com/callback
        response_types:
        - code
        skip_consent: 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.
    ClientSecretResponse:
      type: object
      description: Response for client secret regeneration
      required:
      - client_secret
      properties:
        client_secret:
          type: string
          description: The newly generated client secret
          example: new_client_secret_abc123
      example:
        client_secret: new_client_secret_abc123
  parameters:
    TenantIdHeader:
      name: tenant-id
      in: header
      description: tenant-id of the client integrating with guardian
      required: true
      schema:
        type: string