LuckPanda API keys API

openapi: 3.2.0
info:
  title: Luckpanda App API keys API
  version: 1.0.0
  description: 'Operations tagged API keys across 2 of this provider''s published API definitions: openapi.yaml, luckpanda-app-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://luckpanda.app/api/v1
- url: http://127.0.0.1:8787/api/v1
  description: Local `wrangler dev`
security:
- bearerAuth: []
tags:
- name: API Keys
  description: People only (a signed-in session); a key cannot manage keys
paths:
  /api-keys:
    get:
      tags:
      - API Keys
      operationId: listApiKeys
      responses:
        '200':
          description: Keys (never the secret part)
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
                  next_cursor:
                    type: 'null'
      summary: List api keys
      x-summary-source: derived
    post:
      tags:
      - API Keys
      operationId: createApiKey
      summary: Make an agent key or a server-integration key; the key is in this answer only
      description: A signed-in person with `agent.manage` and `permission.grant`. Grants cannot exceed the person's own.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyInput'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiKey'
                - type: object
                  required:
                  - api_key
                  - principal_id
                  properties:
                    api_key:
                      type: string
                      pattern: ^lpk_
                    principal_id:
                      $ref: '#/components/schemas/Uuid'
        '403':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /api-keys/{keyId}:
    delete:
      tags:
      - API Keys
      operationId: revokeApiKey
      description: The key stops working at once (401).
      parameters:
      - name: keyId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/Uuid'
                  revoked:
                    type: boolean
        '404':
          $ref: '#/components/responses/Problem'
      summary: Revoke api key
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
components:
  responses:
    Problem:
      description: Typed RFC 7807 error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    ApiKey:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        type:
          type: string
          enum:
          - agent
          - integration
        name:
          type: string
        key_prefix:
          type: string
        grants:
          type: array
          items:
            type: string
        limits:
          oneOf:
          - $ref: '#/components/schemas/IntegrationLimits'
          - type: 'null'
        created_at:
          type: string
          format: date-time
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
        created_by:
          type:
          - string
          - 'null'
    IntegrationLimits:
      type: object
      properties:
        kinds:
          type: array
          items:
            type: string
            enum:
            - invoice
            - credit_note
            - debit_note
            - receipt
            - proforma
            - quote
          default:
          - invoice
          - credit_note
        legal_entity_ids:
          type: array
          items:
            $ref: '#/components/schemas/Uuid'
          description: Empty = every legal entity.
        max_total_minor:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Largest document total in any currency without its own limit.
        max_total_by_currency:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
          description: 'Largest document total per currency, e.g. {"USD": 100000}.'
    Problem:
      type: object
      required:
      - type
      - title
      - status
      - code
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: 'VALIDATION_FAILED (422) the body or a field is wrong; see field_errors.

            FORBIDDEN (401 no or revoked key, 403 missing permission or grant).

            NOT_FOUND (404).

            APPROVAL_REQUIRED (403) an agent (or any key over /mcp) tried to issue, send or pay; send proposal_only to propose instead.

            INTEGRATION_LIMIT (403) a server-integration key is outside its kinds, legal entities or largest total.

            PAYWALL (402) the business has not unlocked the outcome (issuing needs the Sales module); the body names the module.

            INVALID_STATE (409) the document is not in a state that allows this (e.g. issuing a cancelled document).

            STALE_VERSION (409) expected_version is behind; reload and retry.

            IDEMPOTENCY_MISMATCH (409) the idempotency_key was used with a different body.

            DUPLICATE_EXTERNAL_REF (409) a document of this kind already has this external_ref.

            COMPLIANCE_BLOCKED (409) a compliance rule blocks the change (e.g. cancelling a document with an active e-invoice IRN).

            ALLOCATION_EXCEEDS_AVAILABLE (409) a payment allocation is more than the receipt or the amount due allows.

            NOT_IMPLEMENTED (501) a path or option that is planned but not served.

            DELIVERY_FAILED (502, /invoices send step) the email provider refused the message.

            RATE_LIMITED (429).

            '
          enum:
          - VALIDATION_FAILED
          - FORBIDDEN
          - NOT_FOUND
          - APPROVAL_REQUIRED
          - INTEGRATION_LIMIT
          - PAYWALL
          - INVALID_STATE
          - STALE_VERSION
          - IDEMPOTENCY_MISMATCH
          - DUPLICATE_EXTERNAL_REF
          - COMPLIANCE_BLOCKED
          - ALLOCATION_EXCEEDS_AVAILABLE
          - CONFLICT
          - NOT_IMPLEMENTED
          - DELIVERY_FAILED
          - RATE_LIMITED
          - INTERNAL_ERROR
        message:
          type: string
        field_errors:
          type: array
          items:
            type: object
            required:
            - path
            - code
            properties:
              path:
                type: string
              code:
                type: string
        correlation_id:
          $ref: '#/components/schemas/Uuid'
    ApiKeyInput:
      type: object
      properties:
        type:
          type: string
          enum:
          - agent
          - integration
          default: agent
        name:
          type: string
          maxLength: 150
        grants:
          type: array
          description: 'Integration keys only. Default: every grant except payment_link.create:sales.'
          items:
            type: string
            enum:
            - company.read_context
            - resource.read
            - party.create
            - party.update
            - document.create:sales
            - document.issue:sales
            - document.send:sales
            - payment.record:sales
            - payment_link.create:sales
        limits:
          $ref: '#/components/schemas/IntegrationLimits'
      additionalProperties: false
    Uuid:
      type: string
      format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque API key, lpk_...
      description: Made in Workspace > Developers (agent or server-integration). Not a JWT.
x-refined-from:
- openapi.yaml
- luckpanda-app-openapi.yaml