openapi: 3.0.4
info:
  title: P0 API Key Management API
  version: 1.0.0
servers:
  - url: https://api.p0.app/o/{orgId}
    variables:
      orgId:
        default: demo-org
        description: The organization ID
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  parameters:
    keyId:
      name: keyId
      in: path
      required: true
      description: The ID of the API key
      schema:
        type: string
  responses:
    UnauthorizedError:
      description: The caller could not be authenticated.
    BadRequestError:
      description: The request is invalid, for example a missing or duplicate name.
  schemas:
    ApiKeyMetadata:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the API key.
        created:
          type: string
          format: date-time
          description: The time the key was created.
        name:
          type: string
          description: The descriptive name of the key.
        user:
          type: object
          description: The user or service account associated with the key.
    CreateApiKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: A descriptive name for the key. Must be unique within the organization.
    CreateApiKeyResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the API key.
        created:
          type: string
          format: date-time
          description: The time the key was created.
        name:
          type: string
          description: The descriptive name of the key.
        rawApiKey:
          type: string
          description: The plaintext API key. Returned only in this response and never retrievable later.
        user:
          type: object
          description: The user or service account associated with the key.
    DeleteApiKeyResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Indicates the key was deleted.
paths:
  /api-key/keys:
    get:
      summary: List API keys
      description: Returns metadata for every API key in the organization, ordered by creation time. Never returns key material.
      security:
        - bearerAuth: []
      responses:
        200:
          description: A list of API key metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKeyMetadata"
        401:
          $ref: "#/components/responses/UnauthorizedError"
    post:
      summary: Create an API key
      description: Creates a new API key and returns the plaintext key. Requires the Owner role.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateApiKeyRequest"
      responses:
        200:
          description: The created API key, including the plaintext key material.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateApiKeyResponse"
        400:
          $ref: "#/components/responses/BadRequestError"
        401:
          $ref: "#/components/responses/UnauthorizedError"
  /api-key/keys/{keyId}:
    delete:
      summary: Delete an API key
      description: Revokes an API key by ID. Requires the Owner role.
      parameters:
        - $ref: "#/components/parameters/keyId"
      security:
        - bearerAuth: []
      responses:
        200:
          description: The key was deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteApiKeyResponse"
        401:
          $ref: "#/components/responses/UnauthorizedError"
