openapi: 3.0.0
info:
  title: Kalshi Trade API Manual Endpoints account api-keys API
  version: 3.19.0
  description: Manually defined OpenAPI spec for endpoints being migrated to spec-first approach
servers:
- url: https://external-api.kalshi.com/trade-api/v2
  description: Production Trade API server
- url: https://api.elections.kalshi.com/trade-api/v2
  description: Production shared API server, also supported
- url: https://external-api.demo.kalshi.co/trade-api/v2
  description: Demo Trade API server
- url: https://demo-api.kalshi.co/trade-api/v2
  description: Demo shared API server, also supported
tags:
- name: api-keys
  description: API key management endpoints
paths:
  /api_keys:
    get:
      operationId: GetApiKeys
      summary: Get API Keys
      description: ' Endpoint for retrieving all API keys associated with the authenticated user.  API keys allow programmatic access to the platform without requiring username/password authentication. Each key has a unique identifier and name.'
      tags:
      - api-keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      responses:
        '200':
          description: List of API keys retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiKeysResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
    post:
      operationId: CreateApiKey
      summary: Create API Key
      description: ' Endpoint for creating a new API key with a user-provided public key.  This endpoint allows users with Premier or Market Maker API usage levels to create API keys by providing their own RSA public key. The platform will use this public key to verify signatures on API requests.'
      tags:
      - api-keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient API usage level
        '500':
          description: Internal server error
  /api_keys/generate:
    post:
      operationId: GenerateApiKey
      summary: Generate API Key
      description: ' Endpoint for generating a new API key with an automatically created key pair.  This endpoint generates both a public and private RSA key pair. The public key is stored on the platform, while the private key is returned to the user and must be stored securely. The private key cannot be retrieved again.'
      tags:
      - api-keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateApiKeyRequest'
      responses:
        '201':
          description: API key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateApiKeyResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /api_keys/{api_key}:
    delete:
      operationId: DeleteApiKey
      summary: Delete API Key
      description: ' Endpoint for deleting an existing API key.  This endpoint permanently deletes an API key. Once deleted, the key can no longer be used for authentication. This action cannot be undone.'
      tags:
      - api-keys
      security:
      - kalshiAccessKey: []
        kalshiAccessSignature: []
        kalshiAccessTimestamp: []
      parameters:
      - name: api_key
        in: path
        required: true
        description: API key ID to delete
        schema:
          type: string
      responses:
        '204':
          description: API key successfully deleted
        '400':
          description: Bad request - invalid API key ID
        '401':
          description: Unauthorized
        '404':
          description: API key not found
        '500':
          description: Internal server error
components:
  schemas:
    CreateApiKeyRequest:
      type: object
      required:
      - name
      - public_key
      properties:
        name:
          type: string
          description: Name for the API key. This helps identify the key's purpose
        public_key:
          type: string
          description: RSA public key in PEM format. This will be used to verify signatures on API requests
        scopes:
          type: array
          description: List of scopes to grant to the API key. Valid values are 'read' and 'write'. If 'write' is included, 'read' must also be included. Defaults to full access (['read', 'write']) if not provided.
          items:
            type: string
    GenerateApiKeyResponse:
      type: object
      required:
      - api_key_id
      - private_key
      properties:
        api_key_id:
          type: string
          description: Unique identifier for the newly generated API key
        private_key:
          type: string
          description: RSA private key in PEM format. This must be stored securely and cannot be retrieved again after this response
    CreateApiKeyResponse:
      type: object
      required:
      - api_key_id
      properties:
        api_key_id:
          type: string
          description: Unique identifier for the newly created API key
    GenerateApiKeyRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name for the API key. This helps identify the key's purpose
        scopes:
          type: array
          description: List of scopes to grant to the API key. Valid values are 'read' and 'write'. If 'write' is included, 'read' must also be included. Defaults to full access (['read', 'write']) if not provided.
          items:
            type: string
    GetApiKeysResponse:
      type: object
      required:
      - api_keys
      properties:
        api_keys:
          type: array
          description: List of all API keys associated with the user
          items:
            $ref: '#/components/schemas/ApiKey'
    ApiKey:
      type: object
      required:
      - api_key_id
      - name
      - scopes
      properties:
        api_key_id:
          type: string
          description: Unique identifier for the API key
        name:
          type: string
          description: User-provided name for the API key
        scopes:
          type: array
          description: List of scopes granted to this API key. Valid values are 'read' and 'write'.
          items:
            type: string
  securitySchemes:
    kalshiAccessKey:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-KEY
      description: Your API key ID
    kalshiAccessSignature:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-SIGNATURE
      description: RSA-PSS signature of the request
    kalshiAccessTimestamp:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-TIMESTAMP
      description: Request timestamp in milliseconds