openapi: 3.0.1
info:
  title: StackHawk Api Authentication Organizations 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: Organizations
  description: Member management and audit logs
paths:
  /api/v1/org/{orgId}/members:
    get:
      operationId: listMembers
      summary: List Members
      description: List all members of an organization.
      tags:
      - Organizations
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberListResponse'
  /api/v1/org/{orgId}/audit:
    get:
      operationId: getAuditHistory
      summary: Get Audit History
      description: Retrieve audit history for an organization. Enterprise feature.
      tags:
      - Organizations
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: pageToken
        in: query
        schema:
          type: string
      - name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Audit history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditListResponse'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        organizationId:
          type: string
    AuditRecord:
      type: object
      properties:
        id:
          type: string
        userId:
          type: string
        organizationId:
          type: string
        action:
          type: string
        timestamp:
          type: string
          format: date-time
        details:
          type: object
          additionalProperties: true
    AuditListResponse:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/AuditRecord'
        nextPageToken:
          type: string
    MemberListResponse:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/User'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained via /api/v1/auth/login