openapi: 3.0.3
info:
  title: Shoehorn Groups API
  description: |
    Identity provider groups and their role mappings. Group membership comes
    from the IdP; role mappings live in Shoehorn.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /groups:
    get:
      summary: List IdP groups
      description: Returns all identity provider groups known to the system.
      tags: [Groups]
      responses:
        '200':
          description: IdP groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items: { $ref: '#/components/schemas/Group' }

  /groups/{groupName}/roles:
    get:
      summary: Get group role mappings
      description: Returns roles assigned to a specific IdP group.
      tags: [Groups]
      parameters:
        - name: groupName
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Roles mapped to this group
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items: { type: string }

    post:
      summary: Assign role to group
      description: Maps a role to an IdP group. All users in the group receive this role.
      tags: [Groups]
      parameters:
        - name: groupName
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role: { type: string }
      responses:
        '201':
          description: Role assigned to group

  /groups/{groupName}/roles/{roleName}:
    delete:
      summary: Remove role from group
      tags: [Groups]
      parameters:
        - name: groupName
          in: path
          required: true
          schema: { type: string }
        - name: roleName
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Role removed from group

components:
  schemas:
    Group:
      type: object
      properties:
        name: { type: string }
        provider: { type: string, enum: [zitadel, okta, entra-id, keycloak] }
        member_count: { type: integer }
        roles:
          type: array
          items: { type: string }
