Dream Sports OIDC Scope Management API

openapi: 3.2.0
info:
  title: Guardian OIDC Scope Management API
  version: 1.0.0
tags:
- name: OIDC Scope Management
paths:
  /scopes:
    get:
      tags:
      - OIDC Scope Management
      summary: List scopes
      description: "Retrieve a paginated list of scopes for a tenant. \nOptionally filter by scope name using partial matching.\n\n**Query Parameters:**\n- `name`: Filter scopes by name (case-insensitive partial match)\n- `page`: Page number for pagination (starts from 1)\n- `page_size`: Number of items per page (1-100, default: 10)\n"
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: name
        in: query
        required: false
        description: Filter scopes by name (partial match, case-insensitive)
        schema:
          type: string
          example: read
      - 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 scopes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeListResponse'
              examples:
                scope_list:
                  summary: List of scopes
                  value:
                    scopes:
                    - name: openid
                      display_name: OpenID
                      description: OpenID Connect scope
                      claims:
                      - sub
                      icon_url: https://example.com/icons/openid.png
                      is_oidc: true
                    - name: read:profile
                      display_name: Read Profile
                      description: Allows reading user profile information
                      claims:
                      - name
                      - email
                      - profile
                      icon_url: https://example.com/icons/profile.png
                      is_oidc: false
        '400':
          description: Bad Request due to invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_page:
                  summary: Invalid page parameter
                  value:
                    error:
                      code: invalid_request
                      message: page value cannot be less than 1
                invalid_page_size:
                  summary: Invalid page_size parameter
                  value:
                    error:
                      code: invalid_request
                      message: page_size must be between 1 and 100
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - OIDC Scope Management
      summary: Create a new scope
      description: "Create a new scope for a tenant. Scopes define permissions and claims \nthat can be granted to users and applications.\n\n**Predefined OIDC Scope Validation:**\n- `openid`: Must contain only the 'sub' claim\n- `phone`: Must contain 'phone_number' and/or 'phone_number_verified' claims (maximum 2 claims)\n- `email`: Must contain 'email' and/or 'email_verified' claims (maximum 2 claims)\n- `address`: Must contain only the 'address' claim\n\nCustom scopes can have any combination of claims.\n"
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScopeRequest'
            examples:
              custom_scope:
                summary: Custom scope example
                value:
                  name: read:profile
                  display_name: Read Profile
                  description: Allows reading user profile information
                  claims:
                  - name
                  - email
                  - profile
                  icon_url: https://example.com/icons/profile.png
                  is_oidc: false
              openid_scope:
                summary: OpenID scope example
                value:
                  name: openid
                  display_name: OpenID
                  description: OpenID Connect scope
                  claims:
                  - sub
                  icon_url: https://example.com/icons/openid.png
                  is_oidc: true
              phone_scope:
                summary: Phone scope example
                value:
                  name: phone
                  display_name: Phone
                  description: Phone number access
                  claims:
                  - phone_number
                  - phone_number_verified
                  icon_url: https://example.com/icons/phone.png
                  is_oidc: true
              email_scope:
                summary: Email scope example
                value:
                  name: email
                  display_name: Email
                  description: Email access
                  claims:
                  - email
                  - email_verified
                  icon_url: https://example.com/icons/email.png
                  is_oidc: true
              address_scope:
                summary: Address scope example
                value:
                  name: address
                  display_name: Address
                  description: Address information access
                  claims:
                  - address
                  icon_url: https://example.com/icons/address.png
                  is_oidc: true
      responses:
        '201':
          description: Scope created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeResponse'
              examples:
                created_scope:
                  summary: Successfully created scope
                  value:
                    name: read:profile
                    display_name: Read Profile
                    description: Allows reading user profile information
                    claims:
                    - name
                    - email
                    - profile
                    icon_url: https://example.com/icons/profile.png
                    is_oidc: false
        '400':
          description: Bad Request due to missing parameters, invalid data, or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_name:
                  summary: Missing scope name
                  value:
                    error:
                      code: invalid_request
                      message: scope name is required
                invalid_openid_claims:
                  summary: Invalid claims for openid scope
                  value:
                    error:
                      code: invalid_request
                      message: openid scope must only include 'sub' claim
                invalid_phone_claims:
                  summary: Invalid claims for phone scope
                  value:
                    error:
                      code: invalid_request
                      message: phone scope must include 'phone_number' or 'phone_number_verified' claim
                invalid_email_claims:
                  summary: Invalid claims for email scope
                  value:
                    error:
                      code: invalid_request
                      message: email scope must include 'email' or 'email_verified' claim
                invalid_address_claims:
                  summary: Invalid claims for address scope
                  value:
                    error:
                      code: invalid_request
                      message: address scope must include 'address' claim
        '409':
          description: Conflict - Scope with the same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                scope_exists:
                  summary: Scope already exists
                  value:
                    error:
                      code: scope_already_exists
                      message: scope already exists for tenant
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /scopes/{name}:
    put:
      tags:
      - OIDC Scope Management
      summary: Update an existing scope
      description: 'Update an existing scope by name. All fields except the scope name can be updated.

        Partial updates are supported - only provided fields will be updated.


        **Predefined OIDC Scope Validation:**

        - `openid`: Must contain only the ''sub'' claim

        - `phone`: Must contain ''phone_number'' and ''phone_number_verified'' claims (exactly 2 claims)

        - `email`: Must contain ''email'' and ''email_verified'' claims (exactly 2 claims)

        - `address`: Must contain only the ''address'' claim


        **Note:** The scope name cannot be changed. To rename a scope, delete the old one and create a new one.

        '
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: name
        in: path
        required: true
        description: Name of the scope to update
        schema:
          type: string
          example: read:profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScopeRequest'
            examples:
              full_update:
                summary: Update all fields
                value:
                  display_name: Updated Profile Reader
                  description: Updated description for profile reading permissions
                  claims:
                  - name
                  - email
                  - profile
                  - picture
                  icon_url: https://example.com/icons/updated-profile.png
                  is_oidc: false
              partial_update:
                summary: Update only display name
                value:
                  display_name: New Display Name
              claims_update:
                summary: Update only claims
                value:
                  claims:
                  - name
                  - email
              openid_update:
                summary: Update OpenID scope
                value:
                  display_name: Updated OpenID
                  description: Updated OpenID Connect scope
                  claims:
                  - sub
                  is_oidc: true
              phone_update:
                summary: Update Phone scope
                value:
                  display_name: Updated Phone Access
                  claims:
                  - phone_number
                  - phone_number_verified
              email_update:
                summary: Update Email scope
                value:
                  display_name: Updated Email Access
                  claims:
                  - email
                  - email_verified
              address_update:
                summary: Update Address scope
                value:
                  display_name: Updated Address Access
                  claims:
                  - address
      responses:
        '200':
          description: Scope updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeResponse'
              examples:
                updated_scope:
                  summary: Successfully updated scope
                  value:
                    name: read:profile
                    display_name: Updated Profile Reader
                    description: Updated description for profile reading permissions
                    claims:
                    - name
                    - email
                    - profile
                    - picture
                    icon_url: https://example.com/icons/updated-profile.png
                    is_oidc: false
                updated_openid:
                  summary: Updated OpenID scope
                  value:
                    name: openid
                    display_name: Updated OpenID
                    description: Updated OpenID Connect scope
                    claims:
                    - sub
                    icon_url: https://example.com/icons/openid.png
                    is_oidc: true
        '400':
          description: Bad Request due to invalid data or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_openid_claims:
                  summary: Invalid OpenID scope claims
                  value:
                    error:
                      code: invalid_request
                      message: openid scope must only include 'sub' claim
                invalid_phone_claims:
                  summary: Invalid Phone scope claims
                  value:
                    error:
                      code: invalid_request
                      message: phone scope must include 'phone_number' and 'phone_number_verified' claim
                invalid_email_claims:
                  summary: Invalid Email scope claims
                  value:
                    error:
                      code: invalid_request
                      message: email scope must include 'email' and 'email_verified' claim
                invalid_address_claims:
                  summary: Invalid Address scope claims
                  value:
                    error:
                      code: invalid_request
                      message: address scope must include 'address' claim
        '404':
          description: Scope not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                scope_not_found:
                  summary: Scope not found
                  value:
                    error:
                      code: scope_not_found
                      message: Scope not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - OIDC Scope Management
      summary: Delete a scope
      description: "Delete a specific scope by name. This operation is irreversible and will \nremove all associations with this scope.\n\n**Important:** Deleting a scope that is currently in use by applications \nor users may cause authentication and authorization issues.\n"
      parameters:
      - $ref: '#/components/parameters/TenantIdHeader'
      - name: name
        in: path
        required: true
        description: Name of the scope to delete
        schema:
          type: string
          example: read:profile
      responses:
        '204':
          description: Scope deleted successfully
        '404':
          description: Scope not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                scope_not_found:
                  summary: Scope not found
                  value:
                    error:
                      code: not_found
                      message: Scope not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ScopeResponse:
      type: object
      description: Scope information
      required:
      - name
      - is_oidc
      properties:
        name:
          type: string
          description: Unique name of the scope
          example: read:profile
        display_name:
          type: string
          description: Human-readable display name
          example: Read Profile
        description:
          type: string
          description: Detailed description of the scope
          example: Allows reading user profile information
        icon_url:
          type: string
          format: uri
          description: URL to the scope's icon
          example: https://example.com/icons/profile.png
        is_oidc:
          type: boolean
          description: Whether this is an OpenID Connect standard scope
          example: true
        claims:
          type: array
          description: List of claims associated with this scope
          items:
            type: string
            example: name
          example:
          - name
          - email
          - profile
    CreateScopeRequest:
      type: object
      description: Request payload for creating a new scope
      required:
      - name
      - is_oidc
      properties:
        name:
          type: string
          description: "Unique name of the scope. For predefined OIDC scopes (openid, phone, email, address), \nspecific claim validation rules apply:\n- 'openid': Must contain only 'sub' claim\n- 'phone': Must contain 'phone_number' and/or 'phone_number_verified' claims (max 2)\n- 'email': Must contain 'email' and/or 'email_verified' claims (max 2)\n- 'address': Must contain only 'address' claim\n"
          example: read:profile
          minLength: 1
          maxLength: 50
        display_name:
          type: string
          description: Human-readable display name
          example: Read Profile
          maxLength: 100
        description:
          type: string
          description: Detailed description of the scope
          example: Allows reading user profile information
          maxLength: 500
        claims:
          type: array
          description: "List of claims associated with this scope. For predefined OIDC scopes, \nspecific claims are required and validated:\n- openid: ['sub']\n- phone: ['phone_number', 'phone_number_verified'] (one or both)\n- email: ['email', 'email_verified'] (one or both)  \n- address: ['address']\n"
          items:
            type: string
            example: name
          example:
          - name
          - email
          - profile
        icon_url:
          type: string
          format: uri
          description: URL to the scope's icon
          example: https://example.com/icons/profile.png
        is_oidc:
          type: boolean
          description: Whether this is an OpenID Connect standard scope
          example: true
    UpdateScopeRequest:
      type: object
      description: 'Request payload for updating an existing scope. All fields are optional for partial updates.

        The scope name cannot be changed through this endpoint.

        '
      properties:
        display_name:
          type: string
          description: Human-readable display name
          example: Updated Profile Reader
          maxLength: 100
        description:
          type: string
          description: Detailed description of the scope
          example: Updated description for profile reading permissions
          maxLength: 500
        claims:
          type: array
          description: "List of claims associated with this scope. For predefined OIDC scopes, \nspecific claims are required and validated:\n- openid: ['sub'] (exactly 1 claim)\n- phone: ['phone_number', 'phone_number_verified'] (exactly 2 claims)\n- email: ['email', 'email_verified'] (exactly 2 claims)\n- address: ['address'] (exactly 1 claim)\n\nCustom scopes can have any combination of claims.\n"
          items:
            type: string
            example: name
          example:
          - name
          - email
          - profile
          - picture
        icon_url:
          type:
          - string
          - 'null'
          format: uri
          description: URL to the scope's icon
          example: https://example.com/icons/updated-profile.png
        is_oidc:
          type: boolean
          description: Whether this is an OpenID Connect standard scope
          example: 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.
    ScopeListResponse:
      type: object
      description: Paginated list of scopes
      required:
      - scopes
      properties:
        scopes:
          type: array
          description: Array of scope objects
          items:
            $ref: '#/components/schemas/ScopeResponse'
  parameters:
    TenantIdHeader:
      name: tenant-id
      in: header
      description: tenant-id of the client integrating with guardian
      required: true
      schema:
        type: string