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/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 ]
    
    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]