openapi: 3.1.0
info:
  title: Keystack Auth API
  version: 0.1.0
servers:
  - url: /

paths:
  /api/keys:
    get:
      operationId: getJwks
      summary: Get JSON Web Key Set
      tags: [keys]
      responses:
        200:
          description: Success
          content:
            application/json:
              schema: { $ref: "#/components/schemas/JwkSet" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/keys/algorithms:
    get:
      operationId: getKeyAlgorithms
      summary: Get supported key algorithms
      tags: [keys]
      security:
        - bearerAuth: []
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items: { type: string }
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/keys/metadata:
    get:
      operationId: getAllKeysMetadata
      summary: Get all keys metadata
      tags: [keys]
      security:
        - bearerAuth: []
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/KeyMetadata" }
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/key:
    post:
      operationId: generateKey
      summary: Generate new key using provided algorithm
      tags: [keys]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: "#/components/schemas/KeyGenerationReq" }
      responses:
        200:
          description: Success
          content:
            application/json:
              schema: { $ref: "#/components/schemas/KeyMetadata" }
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/key/{uuid}:
    delete:
      operationId: revokeKey
      summary: Revoke existing key
      tags: [ keys ]
      security:
        - bearerAuth: []
      parameters:
        - name: uuid
          in: path
          required: true
          schema: { type: string }
      responses:
        201:
          description: Success
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        404:
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/user/auth:
    post:
      operationId: authWithPassword
      summary: Authenticate a user with email and password
      tags: [users]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: "#/components/schemas/AuthWithPasswordReq" }
      responses:
        200:
          description: Success
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AuthResp" }
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/user/me:
    get:
      operationId: getMyDetails
      summary: Get authenticated user details
      tags: [users]
      security:
        - bearerAuth: []
      responses:
        200:
          description: Success
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserDetails" }
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
  
  /api/user/me/password:
    put:
      operationId: setMyPassword
      summary: Update the authenticated user's password
      tags: [users]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: "#/components/schemas/SetMyPasswordReq" }
      responses:
        200:
          description: Success
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserDetails" }
        401:
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }
        500:
          description: Internal server error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResp" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  
  schemas:
    ErrorResp:
      type: object
      properties:
        status_code: { type: integer }
        status: { type: string }
        error: { type: string }
      required: [ status_code, status, error ]
    
    JwkSet:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: "#/components/schemas/Jwk"
      required: [ keys ]
    
    Jwk:
      type: object
      properties:
        kid: { type: string }
        kty: { type: string }
        alg: { type: string }
        use: { type: string }
        n: { type: string }
        e: { type: string }
      required: [ kid, kty, alg, use, n, e ]
    
    KeyMetadata:
      type: object
      properties:
        uuid: { type: string }
        alg: { type: string }
        created_at: { type: string }
      required: [uuid, alg, created_at]
    
    KeyGenerationReq:
      type: object
      properties:
        alg: { type: string }
      required: [alg]
    
    AuthWithPasswordReq:
      type: object
      properties:
        email: { type: string }
        password: { type: string }
      required: [email, password]
    
    AuthResp:
      type: object
      properties:
        token: { type: string }
        user: { $ref: "#/components/schemas/UserDetails" }
      required: [token, user]
    
    UserDetails:
      type: object
      properties:
        uuid: { type: string }
        email: { type: string }
        password_state: { $ref: "#/components/schemas/UserPasswordState" }
        created_at: { type: string }
      required: [uuid, email, password_state, created_at]
    
    UserPasswordState:
      type: string
      enum: [NotSet, Set, NeedsChange]
    
    SetMyPasswordReq:
      type: object
      properties:
        old_password: { type: string }
        new_password: { type: string }
      required: [old_password, new_password]