openapi: 3.1.0
info:
  title: SSH Key Management Authorized Keys 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: Authorized Keys
  description: Authorized keys management for users
paths:
  /authorized-keys/{username}:
    get:
      operationId: getAuthorizedKeys
      summary: Get Authorized Keys
      description: Returns the authorized keys configured for a specific user.
      tags:
      - Authorized Keys
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Authorized keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizedKeysResponse'
    post:
      operationId: addAuthorizedKey
      summary: Add Authorized Key
      description: Adds a public key to a user's authorized_keys.
      tags:
      - Authorized Keys
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizedKeyCreate'
      responses:
        '201':
          description: Authorized key added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizedKey'
  /authorized-keys/{username}/{keyId}:
    delete:
      operationId: removeAuthorizedKey
      summary: Remove Authorized Key
      description: Removes a key from a user's authorized_keys.
      tags:
      - Authorized Keys
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Key removed
components:
  schemas:
    AuthorizedKeyCreate:
      type: object
      required:
      - publicKey
      properties:
        publicKey:
          type: string
        comment:
          type: string
        options:
          type: string
    AuthorizedKey:
      type: object
      properties:
        id:
          type: string
        publicKey:
          type: string
        comment:
          type: string
        options:
          type: string
          description: authorized_keys options string
        addedAt:
          type: string
          format: date-time
    AuthorizedKeysResponse:
      type: object
      properties:
        username:
          type: string
        keys:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizedKey'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT