openapi: 3.0.1
info:
  title: StackHawk Api Authentication Organization Teams API
  description: The StackHawk Public API provides programmatic access to the StackHawk application and API security testing platform. Manage applications, environments, scan configurations, scan results, findings, repositories, teams, policies, and security reports. Authentication requires obtaining a JWT token via the /api/v1/auth/login endpoint using an API key from the StackHawk platform settings.
  version: 0.0.1
  contact:
    url: https://www.stackhawk.com/
    email: support@stackhawk.com
  termsOfService: https://www.stackhawk.com/terms/
servers:
- url: https://api.stackhawk.com
  description: StackHawk API
security:
- BearerAuth: []
tags:
- name: Organization Teams
  description: Team creation and member assignment
paths:
  /api/v1/org/{orgId}/team:
    post:
      operationId: createTeam
      summary: Create Team
      description: Create a new team in an organization.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTeamRequest'
      responses:
        '200':
          description: Created team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
  /api/v1/org/{orgId}/teams:
    get:
      operationId: listTeams
      summary: Find Teams for Organization
      description: List all teams in an organization.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
  /api/v1/org/{orgId}/team/{teamId}:
    get:
      operationId: getTeam
      summary: Get Team
      description: Retrieve details for a specific team.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    put:
      operationId: updateTeam
      summary: Update Team
      description: Update team information.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamUpdateRequest'
      responses:
        '200':
          description: Updated team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    delete:
      operationId: deleteTeam
      summary: Delete Team
      description: Delete a team from an organization.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Team deleted
  /api/v1/org/{orgId}/team/{teamId}/application:
    put:
      operationId: updateTeamApplications
      summary: Update Team Application
      description: Update the applications assigned to a team.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                applicationIds:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated team applications
  /api/v1/org/{orgId}/user/{userId}/teams:
    get:
      operationId: findTeamsForUser
      summary: Find Teams for User
      description: Retrieve all teams a specific user belongs to.
      tags:
      - Organization Teams
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Teams for user
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
components:
  schemas:
    Team:
      type: object
      properties:
        teamId:
          type: string
        organizationId:
          type: string
        name:
          type: string
        applicationIds:
          type: array
          items:
            type: string
    NewTeamRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
    TeamUpdateRequest:
      type: object
      properties:
        name:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained via /api/v1/auth/login