openapi: 3.0.1
info:
  title: Ampersand public API Key JWT Key API
  version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: JWT Key
paths:
  /projects/{projectIdOrName}/jwt-keys:
    post:
      summary: Ampersand Create a New JWT Key
      description: Creates a new JWT key for the specified project with RSA public key for token verification
      operationId: createJWTKey
      tags:
      - JWT Key
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJWTKeyRequest'
            examples:
              example1:
                summary: Valid RSA JWT key creation
                value:
                  name: production-key-1
                  algorithm: RSA
                  publicKeyPem: '-----BEGIN PUBLIC KEY-----

                    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41

                    fGnJm6gOdrj8ym3rFkEjWT2btf2QisEgQG5WQwTfEUvUNR8JW5FQ0mKJ5I4LhXq6

                    V5gN6kSKs2cUdD8Ky7Lj7kqn6I3l3r3F2fK9MFjZ8tU5z4z4yHdF6W2C3k5vf3f

                    -----END PUBLIC KEY-----

                    '
      responses:
        '201':
          description: JWT key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTKeyResponse'
              examples:
                example1:
                  summary: Successful key creation
                  value:
                    kid: 550e8400-e29b-41d4-a716-446655440000
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
              examples:
                invalidAlgorithm:
                  summary: Unsupported algorithm
                  value:
                    type: https://httpstatuses.com/400
                    title: Bad Request
                    status: 400
                    detail: unsupported algorithm
                    validationIssues:
                    - field: algorithm
                      value: ECDSA
                      detail: only RSA algorithm is supported
                      remedy: use 'RSA' as the algorithm
                invalidPublicKey:
                  summary: Invalid public key format
                  value:
                    type: https://httpstatuses.com/400
                    title: Bad Request
                    status: 400
                    detail: invalid public key
                    validationIssues:
                    - field: publicKeyPem
                      detail: invalid RSA public key in PEM format
                      remedy: provide a valid RSA public key in PEM format
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
              examples:
                projectNotFound:
                  summary: Project does not exist
                  value:
                    type: https://httpstatuses.com/404
                    title: Not Found
                    status: 404
                    detail: project not found
                    validationIssues:
                    - field: projectId
                      detail: project not found
                      remedy: check the project ID and try again
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
    get:
      summary: Ampersand List JWT Keys
      description: Retrieves all JWT keys for the specified project, with optional filtering for active keys only
      operationId: listJWTKeys
      tags:
      - JWT Key
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: active
        in: query
        description: Filter to only return active JWT keys
        required: false
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: List of JWT keys retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JWTKey'
              examples:
                example1:
                  summary: Multiple JWT keys
                  value:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    projectId: 123e4567-e89b-12d3-a456-426614174000
                    label: production-key-1
                    algorithm: RSA
                    publicKeyPem: '-----BEGIN PUBLIC KEY-----

                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41

                      -----END PUBLIC KEY-----

                      '
                    active: true
                    createTime: '2024-01-15T10:30:00Z'
                    updateTime: '2024-01-15T10:30:00Z'
                  - id: 550e8400-e29b-41d4-a716-446655440001
                    projectId: 123e4567-e89b-12d3-a456-426614174000
                    label: development-key-1
                    algorithm: RSA
                    publicKeyPem: '-----BEGIN PUBLIC KEY-----

                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5g6xh6m3iLtUfOqn/W52

                      -----END PUBLIC KEY-----

                      '
                    active: false
                    createTime: '2024-01-10T08:15:00Z'
                    updateTime: '2024-01-12T14:20:00Z'
                emptyList:
                  summary: No JWT keys found
                  value: []
        '400':
          description: Bad request - invalid project ID
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
  /projects/{projectIdOrName}/jwt-keys/{keyId}:
    get:
      summary: Ampersand Get a Specific JWT Key
      description: Retrieves a specific JWT key by its ID within the specified project
      operationId: getJWTKey
      tags:
      - JWT Key
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: keyId
        in: path
        required: true
        schema:
          type: string
        description: The JWT key ID.
      responses:
        '200':
          description: JWT key retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTKey'
              examples:
                example1:
                  summary: Single JWT key details
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    projectId: 123e4567-e89b-12d3-a456-426614174000
                    label: production-key-1
                    algorithm: RSA
                    publicKeyPem: '-----BEGIN PUBLIC KEY-----

                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41

                      -----END PUBLIC KEY-----

                      '
                    active: true
                    createTime: '2024-01-15T10:30:00Z'
                    updateTime: '2024-01-15T10:30:00Z'
        '404':
          description: JWT key not found
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
              examples:
                keyNotFound:
                  summary: Key does not exist
                  value:
                    type: https://httpstatuses.com/404
                    title: Not Found
                    status: 404
                    detail: JWT key not found
                    remedy: check the key ID and project ID are both correct, and try again
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
    patch:
      summary: Ampersand Update a JWT Key
      description: Updates specific fields of a JWT key using field masks. Currently supports updating the 'active' status and 'name' field.
      operationId: updateJWTKey
      tags:
      - JWT Key
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: keyId
        in: path
        required: true
        schema:
          type: string
        description: The JWT key ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchJWTKeyRequest'
            examples:
              deactivateKey:
                summary: Deactivate a JWT key
                value:
                  updateMask:
                  - active
                  jwtKey:
                    active: false
              renameKey:
                summary: Rename a JWT key
                value:
                  updateMask:
                  - name
                  jwtKey:
                    name: updated-key-name
              updateMultiple:
                summary: Update both name and active status
                value:
                  updateMask:
                  - active
                  - name
                  jwtKey:
                    active: false
                    name: deprecated-key
      responses:
        '200':
          description: JWT key updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTKey'
              examples:
                example1:
                  summary: Updated JWT key
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    projectId: 123e4567-e89b-12d3-a456-426614174000
                    label: updated-key-name
                    algorithm: RSA
                    publicKeyPem: '-----BEGIN PUBLIC KEY-----

                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41

                      -----END PUBLIC KEY-----

                      '
                    active: false
                    createTime: '2024-01-15T10:30:00Z'
                    updateTime: '2024-01-16T15:45:00Z'
        '400':
          description: Bad request - invalid update mask or missing project/key ID
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
              examples:
                invalidMask:
                  summary: Invalid update mask
                  value:
                    type: https://httpstatuses.com/400
                    title: Bad Request
                    status: 400
                    detail: Invalid update mask
                    remedy: 'Allowed masks: ''active'' and ''name'''
        '404':
          description: JWT key not found
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
        '422':
          description: Unprocessable entity - value not found for mask
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
              examples:
                missingValue:
                  summary: Missing value for update mask
                  value:
                    type: https://httpstatuses.com/422
                    title: Unprocessable Entity
                    status: 422
                    detail: value not found for mask
                    validationIssues:
                    - field: jwtKey
                      detail: required field missing for specified mask
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
    delete:
      summary: Ampersand Delete a JWT Key
      description: Permanently deletes a JWT key from the specified project
      operationId: deleteJWTKey
      tags:
      - JWT Key
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: keyId
        in: path
        required: true
        schema:
          type: string
        description: The JWT key ID.
      responses:
        '204':
          description: JWT key deleted successfully (no content)
        '404':
          description: JWT key not found
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
              examples:
                keyNotFound:
                  summary: Key does not exist
                  value:
                    type: https://httpstatuses.com/404
                    title: Not Found
                    status: 404
                    detail: JWT key not found
                    remedy: check the key ID and project ID are both correct, and try again
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: ../problem/problem.yaml#/components/schemas/ApiProblem
components:
  schemas:
    PatchJWTKeyRequest:
      type: object
      required:
      - updateMask
      - jwtKey
      properties:
        updateMask:
          type: array
          description: List of field paths to update (currently supports 'active' and 'name')
          items:
            type: string
            enum:
            - active
            - label
          minItems: 1
          example:
          - active
          - label
        jwtKey:
          type: object
          description: Object containing the fields to update with their new values
          additionalProperties: true
          properties:
            active:
              type: boolean
              description: New active status for the JWT key
              example: false
            label:
              type: string
              description: New label for the JWT key
              example: updated-key-name
          example:
            active: false
            name: updated-key-name
    JWTKeyResponse:
      type: object
      required:
      - kid
      properties:
        kid:
          type: string
          format: uuid
          description: The unique key identifier (key ID) for the created JWT key
          example: 550e8400-e29b-41d4-a716-446655440000
    JWTKey:
      type: object
      required:
      - id
      - projectId
      - label
      - algorithm
      - publicKeyPem
      - active
      - createTime
      - updateTime
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the JWT key
          example: 550e8400-e29b-41d4-a716-446655440000
        projectId:
          type: string
          format: uuid
          description: The project this JWT key belongs to
          example: 123e4567-e89b-12d3-a456-426614174000
        label:
          type: string
          description: Human-readable name for the JWT key
          example: production-key-1
        algorithm:
          type: string
          description: The cryptographic algorithm used
          enum:
          - RSA
          example: RSA
        publicKeyPem:
          type: string
          description: RSA public key in PEM format
          format: pem
          example: '-----BEGIN PUBLIC KEY-----

            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41

            -----END PUBLIC KEY-----

            '
        active:
          type: boolean
          description: Whether the JWT key is currently active and can be used for verification
          example: true
        createTime:
          type: string
          format: date-time
          description: Timestamp when the JWT key was created
          example: '2024-01-15T10:30:00Z'
        updateTime:
          type: string
          format: date-time
          description: Timestamp when the JWT key was last updated
          example: '2024-01-15T10:30:00Z'
    CreateJWTKeyRequest:
      type: object
      required:
      - label
      - algorithm
      - publicKeyPem
      properties:
        label:
          type: string
          description: Human-readable label for the JWT key
          minLength: 1
          maxLength: 255
          example: production-key-1
        algorithm:
          type: string
          description: The cryptographic JWT signing algorithm (currently only RS256 is supported)
          enum:
          - RS256
          example: RS256
        publicKeyPem:
          type: string
          description: RSA public key in PEM format for JWT signature verification
          format: pem
          example: '-----BEGIN PUBLIC KEY-----

            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41

            fGnJm6gOdrj8ym3rFkEjWT2btf2QisEgQG5WQwTfEUvUNR8JW5FQ0mKJ5I4LhXq6

            V5gN6kSKs2cUdD8Ky7Lj7kqn6I3l3r3F2fK9MFjZ8tU5z4z4yHdF6W2C3k5vf3f

            -----END PUBLIC KEY-----

            '
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: X-Api-Key
      in: header
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT