step-ca-webui/docs/core-api.md

API specification for Core API

openapi: 3.0.0
info:
  title: Step-CA Management API
  version: 0.0.1
  description: API for managing step-ca Certificate Authority

servers:
  - url: https://api.example.com/v1

paths:
  /certificates:
    get:
      summary: List all certificates
      parameters:
        - name: preview
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Certificate'
                  - $ref: '#/components/schemas/CommandPreview'

  /certificates/generate:
    post:
      summary: Generate certificate
      parameters:
        - name: preview
          in: query
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateGenerateRequest'
      responses:
        '200':
          description: Command preview or generation result
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CertificateGenerateResult'
                  - $ref: '#/components/schemas/CommandPreview'

  /certificates/renew:
    post:
      summary: Preview renew certificate command
      parameters:
        - name: certId
          in: query
          required: true
          schema:
            type: string
        - name: duration
          in: query
          required: true
          schema:
            type: integer
            description: "Duration in seconds"
        - name: preview
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Command preview
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CertificateRenewResult'
                  - $ref: '#/components/schemas/CommandPreview'

  /certificates/revoke:
    post:
      summary: Preview revoke certificate command
      parameters:
        - name: certId
          in: query
          required: true
          schema:
            type: string
        - name: preview
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Command preview
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CertificateRevokeResult'
                  - $ref: '#/components/schemas/CommandPreview'

  /logs/single:
    get:
      summary: Get log entry by ID
      parameters:
        - name: logId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogEntry'


  /logs:
    get:
      summary: Retrieve logs
      parameters:
        - name: severity
          in: query
          schema:
            type: array
            items:
              type: string
              enum: [ DEBUG, INFO, WARN, ERROR ]
        - name: traceId
          in: query
          schema:
            type: string
            description: "UUID format"
        - name: commandsOnly
          in: query
          schema:
            type: boolean
        - name: page
          in: query
          schema:
            type: integer
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogEntry'

components:
  schemas:
    Certificate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum: [ Active, Expired, Revoked ]
        expirationDate:
          type: string
          format: date-time

    CertificateGenerateRequest:
      type: object
      properties:
        keyName:
          type: string
        keyType:
          type: string
          enum: [ RSA, ECDSA ]
        duration:
          type: string

    CommandPreview:
      type: object
      properties:
        command:
          type: string

    CertificateGenerateResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        logEntryId:
          type: string
        certificateId:
          type: string
        certificateName:
          type: string
        expirationDate:
          type: string
          format: date-time

    CertificateRenewResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        logEntryId:
          type: string
        certificateId:
          type: string
        newExpirationDate:
          type: string
          format: date-time

    CertificateRevokeResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        logEntryId:
          type: string
        certificateId:
          type: string
        revocationDate:
          type: string
          format: date-time

    LogEntry:
      type: object
      properties:
        entry_id:
          type: integer
        timestamp:
          type: string
          format: date-time
        severity:
          type: string
          enum: [ DEBUG, INFO, WARN, ERROR ]
        message:
          type: string
        traceId:
          type: string
          description: "UUID format"
        commandInfo:
          $ref: '#/components/schemas/CommandInfo'
          nullable: true
          description: Contains command execution info, if entry is related to command

    CommandInfo:
      type: object
      properties:
        command:
          type: string
        output:
          type: string
        exitCode:
          type: integer