payments-ai API Keys API

openapi: 3.2.0
info:
  title: Payments AI MoR Merchant Public API Keys API
  version: 1.0.0
  description: Merchant Public API, partner onboarding, and buyer checkout endpoints. Authenticate every call with a Merchant API Key (pai_test_* / pai_live_*). The same key reaches its own merchant resources and those of any sub-merchant it has onboarded via POST /v1/public-api/merchants.
servers:
- url: https://sandbox.mor.payments.ai/api
  description: Sandbox API
tags:
- name: API Keys
  description: List, create, and revoke Merchant API keys for your merchant or any sub-merchant in your allowed set.
paths:
  /v1/public-api/merchants/{merchantId}/api-keys:
    get:
      operationId: PublicApiApiKeys_list
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicApiApiKeySummary'
      tags:
      - API Keys
      summary: List API keys
    post:
      operationId: PublicApiApiKeys_create
      description: Mint a key. Omitting `permissions` creates a key with none. A non-empty `permissions` returns 403 `api_key.permission_forbidden` and records `api_key_permission_grant_denied`.
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCreateApiKeyResponse'
        '403':
          description: Access is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - API Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCreateApiKeyRequest'
      summary: Create API key
  /v1/public-api/merchants/{merchantId}/api-keys/{id}:
    delete:
      operationId: PublicApiApiKeys_revoke
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
      tags:
      - API Keys
      summary: Revoke API key
components:
  schemas:
    PublicApiCreateApiKeyRequest:
      type: object
      required:
      - name
      - environment
      properties:
        name:
          type: string
          maxLength: 128
        environment:
          type: string
          enum:
          - sandbox
          - live
        permissions:
          type: array
          items:
            type: string
            enum:
            - payouts:write
          description: Not a grant. A non-empty list returns 403 `api_key.permission_forbidden`. Permissions are granted from the dashboard only.
    PublicApiApiKeySummary:
      type: object
      required:
      - id
      - name
      - maskedKey
      - environment
      - permissions
      - lastUsedAt
      - createdAt
      properties:
        id:
          type: string
        name:
          type: string
        maskedKey:
          type: string
        environment:
          type: string
          enum:
          - sandbox
          - live
        permissions:
          type: array
          items:
            type: string
            enum:
            - payouts:write
          description: Opt-in capabilities granted to this key. Granted from the dashboard only; a key cannot grant permissions when minting another key.
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
    PublicApiCreateApiKeyResponse:
      type: object
      required:
      - key
      - maskedKey
      - id
      - createdAt
      properties:
        key:
          type: string
          description: Plaintext key, returned exactly once. Only its hash is persisted — store it now.
        maskedKey:
          type: string
        id:
          type: string
        createdAt:
          type: string
          format: date-time
    ApiError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code (e.g. `product.not_found`, `invalid_request`).
        message:
          type: string
          description: Human-readable error message suitable for display or logs.
        docUrl:
          type: string
          format: uri
          description: 'Optional Fix-It guide URL. v1 invariant: `https://doc.mor.payments.ai/errors/{slug}` where `slug` is kebab-case derived from the internal domain error code (see model doc).'
      description: Standard API error response with optional documentation link.
  securitySchemes:
    UserOAuthCredentialAuth:
      type: http
      scheme: Bearer
      description: 'Signed-in user OAuth credential (`pai_mcp_*`) issued through the dashboard consent screen for this API: the authorization and token requests name the RFC 8707 resource `<API_URL>/v1/public-api` (ADR-0020). Credentials issued for the MCP server, or for no resource, are rejected with 401 `auth.invalid_token` and `WWW-Authenticate: Bearer resource_metadata="<API_URL>/.well-known/oauth-protected-resource/v1/public-api", error="invalid_token"`. Valid on the environment that issued it only. Each operation that accepts it names one required permission; a missing permission is 403 `auth.insufficient_scope` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="<permission>"`. A merchant outside the user''s active memberships is 403 `merchant.access_forbidden`; a team role below the operation''s minimum is 403 `team.role_forbidden`.'
    MerchantApiKeyAuth:
      type: http
      scheme: Bearer
      description: 'Merchant API key from Developer Tools → API Keys. Example: `Authorization: Bearer pai_test_...`. Also accepted for any active sub-merchant this key''s own merchant created.'