openapi: 3.0.1
info:
  title: StackHawk Api Authentication 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: Api Authentication
  description: Token management and login
paths:
  /api/v1/auth/login:
    get:
      operationId: login
      summary: Login With API Key
      description: Authenticate using an API key to obtain a JWT access token. The API key is passed in the X-ApiKey header. Tokens expire after 30 minutes.
      tags:
      - Api Authentication
      security: []
      parameters:
      - name: X-ApiKey
        in: header
        required: true
        schema:
          type: string
        description: StackHawk API key from Settings > API Keys
      responses:
        '200':
          description: JWT token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWT'
  /api/v1/auth/refresh-token:
    get:
      operationId: refreshToken
      summary: Refresh Token
      description: Refresh an existing JWT access token before it expires.
      tags:
      - Api Authentication
      responses:
        '200':
          description: Refreshed JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWT'
components:
  schemas:
    JWT:
      type: object
      properties:
        token:
          type: string
          description: JWT access token
        expiresAt:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained via /api/v1/auth/login