openapi: 3.1.0
info:
  title: SSH Key Management Authorized Keys Certificates API
  description: A REST API for managing SSH keys, certificates, and access policies in infrastructure environments. Provides endpoints for key generation, certificate signing, authorized keys management, and host key verification. This represents common SSH management capabilities available via OpenSSH tooling and SSH certificate authority implementations.
  version: '1.0'
  contact:
    name: OpenSSH Project
    url: https://www.openssh.com/
  license:
    name: BSD License
    url: https://www.openssh.com/portable.html
servers:
- url: https://api.openssh.example.com/v1
  description: SSH Management API
security:
- BearerAuth: []
tags:
- name: Certificates
  description: SSH certificate authority and certificate signing
paths:
  /certificates:
    post:
      operationId: signCertificate
      summary: Sign SSH Certificate
      description: Signs an SSH public key with the certificate authority, creating a short-lived SSH certificate. Certificates enable time-limited access without managing authorized_keys files.
      tags:
      - Certificates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateSignRequest'
      responses:
        '201':
          description: Certificate signed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSHCertificate'
    get:
      operationId: listCertificates
      summary: List Certificates
      description: Returns issued SSH certificates with their validity periods and principals.
      tags:
      - Certificates
      parameters:
      - name: principal
        in: query
        description: Filter by principal (username)
        schema:
          type: string
      - name: hostKey
        in: query
        description: Filter host certificates
        schema:
          type: boolean
      - name: expired
        in: query
        description: Include expired certificates
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Certificate list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateListResponse'
components:
  schemas:
    CertificateListResponse:
      type: object
      properties:
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/SSHCertificate'
        total:
          type: integer
    SSHCertificate:
      type: object
      properties:
        certificate:
          type: string
          description: Signed certificate in OpenSSH certificate format
        serialNumber:
          type: integer
        principals:
          type: array
          items:
            type: string
        validAfter:
          type: string
          format: date-time
        validBefore:
          type: string
          format: date-time
        keyId:
          type: string
        certType:
          type: string
          enum:
          - user
          - host
        fingerprint:
          type: string
    CertificateSignRequest:
      type: object
      required:
      - publicKey
      - principals
      properties:
        publicKey:
          type: string
          description: Public key to sign in OpenSSH format
        principals:
          type: array
          items:
            type: string
          description: List of usernames or hostnames the certificate is valid for
        validityPeriod:
          type: string
          description: Certificate validity period (e.g., 8h, 1d, 30d)
          default: 8h
        certType:
          type: string
          enum:
          - user
          - host
          default: user
        extensions:
          type: object
          description: Certificate extensions (e.g., permit-pty, permit-user-rc)
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT