openapi: 3.1.0
info:
  title: Sendblue Apple Wallet Pass API
  version: 1.0.0
  description: Tenant-scoped pass issuance, recipient install links, Apple Wallet updates. Templates use a deliberately
    bounded subset of pass.json; unknown keys are rejected. No dashboard.
servers:
  - url: https://wallet.example.com
    description: Replace with PUBLIC_BASE_URL
paths:
  /api/v1/templates:
    get:
      summary: List tenant templates
      operationId: get__api_v1_templates
      security:
        - BearerAuth: []
      parameters: &a11
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Template"
                  limit:
                    type: integer
                  offset:
                    type: integer
                required:
                  - data
                  - limit
                  - offset
        "400": &a1
          description: Malformed JSON, invalid cursor, or invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401": &a2
          description: Missing or invalid credential
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404": &a3
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409": &a4
          description: Resource conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413": &a5
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "415": &a6
          description: Expected application/json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422": &a7
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500": &a8
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a validated template
      operationId: post__api_v1_templates
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateInput"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/templates/{id}:
    get:
      summary: Get a template
      operationId: get__api_v1_templates__id_
      security:
        - BearerAuth: []
      parameters: &a9
        - in: path
          name: id
          required: true
          schema: &a10
            type: string
            format: uuid
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    put:
      summary: Replace a template
      operationId: put__api_v1_templates__id_
      description: A complete replacement. Only future issues use this definition; already issued passes keep their snapshot.
      security:
        - BearerAuth: []
      parameters: *a9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateInput"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    delete:
      summary: Delete an unused template
      operationId: delete__api_v1_templates__id_
      description: Returns 409 when any pass refers to this template.
      security:
        - BearerAuth: []
      parameters: *a9
      responses:
        "204":
          description: No content
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/assets:
    post:
      summary: Upload a tenant PNG asset
      operationId: post__api_v1_assets
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                pngBase64:
                  type: string
                  contentEncoding: base64
                  description: Raw base64 PNG, without data URL prefix; maximum decoded size 2 MB, 4 million pixels. Dimensions checked
                    again against the chosen template slot.
              required:
                - pngBase64
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/passes:
    post:
      summary: Issue a personalized pass
      operationId: post__api_v1_passes
      description: Creates a stable serial number and unguessable bearer install URL. Expiring the install link does not
        disable updates to a pass already in Wallet.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                templateId: *a10
                variables:
                  $ref: "#/components/schemas/Variables"
                tokenExpiresAt: &a12
                  type: string
                  format: date-time
              required:
                - templateId
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pass"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    get:
      summary: List issued passes
      operationId: get__api_v1_passes
      security:
        - BearerAuth: []
      parameters: *a11
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Pass"
                  limit:
                    type: integer
                  offset:
                    type: integer
                required:
                  - data
                  - limit
                  - offset
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/usage:
    get:
      summary: Get monthly Wallet usage for the authenticated workspace
      operationId: get__api_v1_usage
      security:
        - BearerAuth: []
      parameters:
        - in: query
          name: month
          description: UTC calendar month. Defaults to the current UTC month.
          schema: &a27
            type: string
            pattern: ^[1-9]\d{3}-(0[1-9]|1[0-2])$
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonthlyUsage"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/passes/{id}:
    get:
      summary: Get a pass and its active registration count
      operationId: get__api_v1_passes__id_
      security:
        - BearerAuth: []
      parameters: *a9
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pass"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    patch:
      summary: Update variable values or expiration and queue APNs notifications
      operationId: patch__api_v1_passes__id_
      description: Supply at least one property. Variables merge with stored values. A null expirationDate clears expiration.
        Voiding is irreversible in this API. Push work is committed transactionally and delivered by the worker.
      security:
        - BearerAuth: []
      parameters: *a9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                variables:
                  $ref: "#/components/schemas/Variables"
                expirationDate:
                  anyOf:
                    - *a12
                    - type: "null"
              required: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pass"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/passes/{id}/void:
    post:
      summary: Void a pass and queue notifications
      operationId: post__api_v1_passes__id__void
      security:
        - BearerAuth: []
      parameters: *a9
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pass"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/passes/{id}/expire:
    post:
      summary: Expire a pass and queue notifications
      operationId: post__api_v1_passes__id__expire
      security:
        - BearerAuth: []
      parameters: *a9
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pass"
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/passes/{id}/send:
    post:
      summary: Send an install link through Sendblue
      operationId: post__api_v1_passes__id__send
      description: Uses configured Sendblue account and sender. Optional message precedes the link. Accepted is not delivery
        confirmation. No automatic retry (avoids duplicate messages).
      security:
        - BearerAuth: []
      parameters: *a9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                phoneNumber:
                  type: string
                  pattern: ^\+[1-9]\d{7,14}$
                message:
                  type: string
                  maxLength: 1000
              required:
                - phoneNumber
      responses:
        "202":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  accepted:
                    type: boolean
                required:
                  - accepted
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
        "502":
          description: Sendblue rejected the message
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Sendblue is not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/v1/keys:
    get:
      summary: List key metadata
      operationId: get__api_v1_keys
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/KeyMetadata"
                required:
                  - data
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    post:
      summary: Create a tenant API key
      operationId: post__api_v1_keys
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                label:
                  type: string
                  minLength: 1
                  maxLength: 100
              required:
                - label
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id: *a10
                  label: &a13
                    type: string
                  key:
                    type: string
                    description: Returned once; store securely.
                required:
                  - id
                  - label
                  - key
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/keys/{id}:
    delete:
      summary: Revoke an API key
      operationId: delete__api_v1_keys__id_
      description: Can revoke the current or last key; create a replacement before doing so.
      security:
        - BearerAuth: []
      parameters: *a9
      responses:
        "204":
          description: No content
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/signer:
    get:
      summary: Inspect active signer selection and tenant profiles
      operationId: get__api_v1_signer
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  activeSignerId:
                    anyOf:
                      - *a10
                      - type: "null"
                  usesDefault:
                    type: boolean
                  profiles:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        id: *a10
                        passTypeIdentifier: *a13
                        teamIdentifier: *a13
                      required:
                        - id
                        - passTypeIdentifier
                        - teamIdentifier
                required:
                  - activeSignerId
                  - usesDefault
                  - profiles
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    put:
      summary: Set or renew tenant signing credentials
      operationId: put__api_v1_signer
      description: Credentials are AES-256-GCM encrypted at rest. Renewing the same Pass Type ID updates its profile for
        existing passes. Switching IDs selects a new profile for future passes; old passes remain pinned to their
        original profile. The certificate UID/OU and private key must match.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignerInput"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id: *a10
                  passTypeIdentifier: *a13
                  teamIdentifier: *a13
                required:
                  - id
                  - passTypeIdentifier
                  - teamIdentifier
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    delete:
      summary: Use the default signer for future issues
      operationId: delete__api_v1_signer
      description: Retains tenant profiles so already issued passes remain signable.
      security:
        - BearerAuth: []
      responses:
        "204":
          description: No content
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/webhooks:
    get:
      summary: List tenant webhook subscriptions
      operationId: get__api_v1_webhooks
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Webhook"
                required:
                  - data
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    post:
      summary: Subscribe to pass.installed, pass.removed and pass.viewed
      operationId: post__api_v1_webhooks
      description: 'HTTPS on port 443, public IPs only. All three event types are subscribed. Requests carry
        X-Sendblue-Timestamp, X-Sendblue-Event-Id and X-Sendblue-Signature: v1=<HMAC-SHA256(timestamp + "." + rawBody)>.
        At-least-once delivery; deduplicate on event.id. Validate timestamp freshness.'
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                url:
                  type: string
                  format: uri
              required:
                - url
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id: *a10
                  url: *a13
                  secret:
                    type: string
                    description: Returned once. HMAC signing secret.
                required:
                  - id
                  - url
                  - secret
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/v1/webhooks/{id}:
    delete:
      summary: Delete a webhook subscription
      operationId: delete__api_v1_webhooks__id_
      security:
        - BearerAuth: []
      parameters: *a9
      responses:
        "204":
          description: No content
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /{client}/{token}:
    get:
      summary: Open the hosted Apple Wallet pass page
      operationId: get___client___token_
      description: Shows the issuer, artwork, and an explicit install action on iOS. Desktop includes a QR code to the same
        page. Message previews use Open Graph metadata. The token is a bearer credential. Responses use no-store and
        no-referrer.
      security: []
      parameters:
        - &a14
          in: path
          name: client
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 64
        - &a15
          in: path
          name: token
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{43}$
      responses:
        "200":
          description: Recipient response
          content:
            text/html:
              schema: *a13
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "410":
          description: Install token expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /{client}/{token}.pkpass:
    get:
      summary: Download a signed Apple Wallet pass
      operationId: get___client___token__pkpass
      description: The hosted page links here from its Add to Apple Wallet button. The token is a bearer credential. Responses
        use no-store and no-referrer.
      security: &a16 []
      parameters:
        - *a14
        - *a15
      responses:
        "200": &a17
          description: Recipient response
          content:
            application/vnd.apple.pkpass:
              schema:
                type: string
                format: binary
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "410": &a18
          description: Install token expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /p/{token}.pkpass:
    get:
      summary: "Legacy URL: Download a signed Apple Wallet pass"
      operationId: get__p__token__pkpass
      description: The hosted page links here from its Add to Apple Wallet button. The token is a bearer credential. Responses
        use no-store and no-referrer.
      security: *a16
      parameters: &a20
        - *a15
      responses:
        "200": *a17
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "410": *a18
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /{client}/{token}.png:
    get:
      summary: Render share artwork (1200 × 630 PNG)
      operationId: get___client___token__png
      description: Uses the template share image or Wallet artwork and issuer branding. Recipient fields and barcodes are
        excluded. The token is a bearer credential. Responses use no-store and no-referrer.
      security: &a19 []
      parameters:
        - *a14
        - *a15
      responses:
        "200": &a21
          description: Recipient response
          content:
            image/png:
              schema:
                type: string
                format: binary
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "410": &a22
          description: Install token expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /p/{token}.png:
    get:
      summary: "Legacy URL: Render share artwork (1200 × 630 PNG)"
      operationId: get__p__token__png
      description: Uses the template share image or Wallet artwork and issuer branding. Recipient fields and barcodes are
        excluded. The token is a bearer credential. Responses use no-store and no-referrer.
      security: *a19
      parameters: *a20
      responses:
        "200": *a21
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "410": *a22
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /p/{token}:
    get:
      summary: Redirect a legacy pass link to its canonical URL
      operationId: get__p__token_
      security: []
      parameters: *a20
      responses:
        "302":
          description: Redirects to the canonical client and pass URL
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "410":
          description: Install token expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/passkit/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}:
    post:
      summary: Register a Wallet device
      operationId: post__api_passkit_v1_devices__deviceLibraryIdentifier__registrations__passTypeIdentifier___serialNumber_
      description: 201 for new registration; 200 for existing. Both are successful. Generates pass.installed only for a new
        registration.
      security:
        - ApplePassAuth: []
      parameters: &a23
        - &a24
          in: path
          name: deviceLibraryIdentifier
          required: true
          schema: *a13
        - &a25
          in: path
          name: passTypeIdentifier
          required: true
          schema: *a13
        - &a26
          in: path
          name: serialNumber
          required: true
          schema: *a10
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                pushToken:
                  type: string
                  pattern: ^[a-fA-F0-9]{32,256}$
              required:
                - pushToken
      responses:
        "200":
          description: Registration already exists; push token refreshed
        "201":
          description: Success
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    delete:
      summary: Unregister a Wallet device
      operationId: delete__api_passkit_v1_devices__deviceLibraryIdentifier__registrations__passTypeIdentifier___serialNumber_
      description: Idempotent. Generates pass.removed only when a registration existed.
      security:
        - ApplePassAuth: []
      parameters: *a23
      responses:
        "200":
          description: Success
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/passkit/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}:
    get:
      summary: Get registered serials updated since an opaque update tag
      operationId: get__api_passkit_v1_devices__deviceLibraryIdentifier__registrations__passTypeIdentifier_
      description: Unauthenticated as required by Apple. The device identifier is unguessable. Omit passesUpdatedSince for the
        initial list. Treat lastUpdated as opaque and send it back unchanged.
      security: []
      parameters:
        - *a24
        - *a25
        - in: query
          name: passesUpdatedSince
          schema: *a13
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  serialNumbers:
                    type: array
                    items: *a13
                  lastUpdated: *a13
                required:
                  - serialNumbers
                  - lastUpdated
        "204":
          description: No matching updated passes
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/passkit/v1/passes/{passTypeIdentifier}/{serialNumber}:
    get:
      summary: Download latest pass for Wallet
      operationId: get__api_passkit_v1_passes__passTypeIdentifier___serialNumber_
      description: Uses the per-pass authenticationToken in ApplePass authorization. Works after the public token expires.
        Returns Last-Modified and ETag.
      security:
        - ApplePassAuth: []
      parameters:
        - *a25
        - *a26
        - in: header
          name: If-Modified-Since
          schema: *a13
        - in: header
          name: If-None-Match
          schema: *a13
      responses:
        "200":
          description: Signed pass
          headers:
            Last-Modified:
              schema: *a13
            ETag:
              schema: *a13
          content:
            application/vnd.apple.pkpass:
              schema:
                type: string
                format: binary
        "304":
          description: Not modified
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/passkit/v1/log:
    post:
      summary: Accept Apple Wallet diagnostic logs
      operationId: post__api_passkit_v1_log
      description: Unauthenticated per Apple specification. Logs only the entry count; does not persist potentially sensitive
        log content.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                logs:
                  type: array
                  maxItems: 100
                  items:
                    type: string
                    maxLength: 2000
              required:
                - logs
      responses:
        "200":
          description: Success
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
  /api/internal/jobs:
    get:
      summary: Process up to 20 queued push/webhook jobs
      operationId: get__api_internal_jobs
      description: Called by Vercel Cron every minute (Pro plan) or an authenticated external scheduler. Eight delivery
        attempts with exponential backoff, 30-second leases, SKIP LOCKED. Terminal jobs remain in Postgres for operator
        inspection.
      security:
        - CronAuth: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  completed:
                    type: integer
                  failed:
                    type: integer
                required:
                  - completed
                  - failed
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
    post:
      summary: Process up to 20 queued push/webhook jobs
      operationId: post__api_internal_jobs
      description: Called by Vercel Cron every minute (Pro plan) or an authenticated external scheduler. Eight delivery
        attempts with exponential backoff, 30-second leases, SKIP LOCKED. Terminal jobs remain in Postgres for operator
        inspection.
      security:
        - CronAuth: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  completed:
                    type: integer
                  failed:
                    type: integer
                required:
                  - completed
                  - failed
        "400": *a1
        "401": *a2
        "404": *a3
        "409": *a4
        "413": *a5
        "415": *a6
        "422": *a7
        "500": *a8
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Tenant API key
    ApplePassAuth:
      type: apiKey
      in: header
      name: Authorization
      description: ApplePass <authenticationToken from signed pass.json>
    CronAuth:
      type: http
      scheme: bearer
      description: CRON_SECRET, not a tenant API key
  schemas:
    MonthlyUsage:
      type: object
      additionalProperties: false
      properties:
        month: *a27
        timezone:
          const: UTC
        workspaceId: *a10
        workspaceName: *a13
        issued:
          type: integer
          minimum: 0
          description: Passes created during the month.
        installed:
          type: integer
          minimum: 0
          description: Passes with their first Wallet registration during the month.
      required:
        - month
        - timezone
        - workspaceId
        - workspaceName
        - issued
        - installed
    Error:
      type: object
      additionalProperties: false
      properties:
        error: *a13
        details:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              path: *a13
              message: *a13
            required:
              - path
              - message
      required:
        - error
    Color:
      type: string
      pattern: ^rgb\(\s*(?:\d{1,3}\s*,\s*){2}\d{1,3}\s*\)$
      description: Each RGB channel 0–255; hexadecimal colors are not accepted.
    Variables:
      type: object
      maxProperties: 100
      propertyNames:
        pattern: ^[A-Za-z][A-Za-z0-9_]{0,63}$
      additionalProperties:
        oneOf:
          - type: string
            maxLength: 2000
          - type: number
      description: Replaces {{variable}} in field values/labels and barcode message/altText. Missing variables fail issuance
        or update.
    Field:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,63}$
        value:
          oneOf:
            - type: string
              maxLength: 1000
            - type: number
        label:
          type: string
          maxLength: 1000
        changeMessage:
          type: string
          description: Exactly one %@ placeholder
        textAlignment:
          enum:
            - PKTextAlignmentLeft
            - PKTextAlignmentCenter
            - PKTextAlignmentRight
            - PKTextAlignmentNatural
        dateStyle:
          enum:
            - PKDateStyleNone
            - PKDateStyleShort
            - PKDateStyleMedium
            - PKDateStyleLong
            - PKDateStyleFull
        timeStyle:
          enum:
            - PKDateStyleNone
            - PKDateStyleShort
            - PKDateStyleMedium
            - PKDateStyleLong
            - PKDateStyleFull
        ignoresTimeZone:
          type: boolean
        isRelative:
          type: boolean
        numberStyle:
          enum:
            - PKNumberStyleDecimal
            - PKNumberStylePercent
            - PKNumberStyleScientific
            - PKNumberStyleSpellOut
        currencyCode:
          type: string
          pattern: ^[A-Z]{3}$
      required:
        - key
        - value
    TemplateInput:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        style:
          enum:
            - generic
            - storeCard
            - coupon
            - eventTicket
        organizationName:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          minLength: 1
          maxLength: 250
        shareImageId:
          type: string
          format: uuid
          description: Optional tenant PNG asset ID for the hosted page and message preview. A 1200 × 630 PNG is recommended.
        logoText:
          type: string
          maxLength: 100
        backgroundColor:
          $ref: "#/components/schemas/Color"
        foregroundColor:
          $ref: "#/components/schemas/Color"
        labelColor:
          $ref: "#/components/schemas/Color"
        images:
          type: object
          propertyNames:
            pattern: ^(icon|logo|strip|thumbnail)(@2x|@3x)?$
          additionalProperties: *a10
          required:
            - icon
            - icon@2x
          description: Tenant asset IDs; icon + icon@2x required. See README for pixel dimensions and supported slots.
        fields:
          type: object
          additionalProperties: false
          properties:
            headerFields:
              type: array
              maxItems: 3
              items:
                $ref: "#/components/schemas/Field"
              default: []
            primaryFields:
              type: array
              maxItems: 1
              items:
                $ref: "#/components/schemas/Field"
              default: []
            secondaryFields:
              type: array
              maxItems: 4
              items:
                $ref: "#/components/schemas/Field"
              default: []
            auxiliaryFields:
              type: array
              maxItems: 4
              items:
                $ref: "#/components/schemas/Field"
              default: []
            backFields:
              type: array
              maxItems: 30
              items:
                $ref: "#/components/schemas/Field"
              default: []
          required: []
        barcode:
          type: object
          additionalProperties: false
          properties:
            format:
              enum:
                - PKBarcodeFormatQR
                - PKBarcodeFormatPDF417
                - PKBarcodeFormatAztec
                - PKBarcodeFormatCode128
            message:
              type: string
              minLength: 1
              maxLength: 2000
            messageEncoding:
              enum:
                - iso-8859-1
                - utf-8
              default: iso-8859-1
            altText:
              type: string
              maxLength: 250
          required:
            - format
            - message
        locations:
          type: array
          maxItems: 10
          items:
            type: object
            additionalProperties: false
            properties:
              latitude:
                type: number
                minimum: -90
                maximum: 90
              longitude:
                type: number
                minimum: -180
                maximum: 180
              altitude:
                type: number
              relevantText:
                type: string
                maxLength: 200
            required:
              - latitude
              - longitude
        relevantDate: *a12
        expirationDate: *a12
      required:
        - name
        - style
        - organizationName
        - description
        - backgroundColor
        - foregroundColor
        - labelColor
        - images
        - fields
    Template:
      type: object
      additionalProperties: false
      properties:
        id: *a10
        tenantId: *a10
        definition:
          $ref: "#/components/schemas/TemplateInput"
        createdAt: *a12
        updatedAt: *a12
      required:
        - id
        - tenantId
        - definition
        - createdAt
        - updatedAt
    Asset:
      type: object
      additionalProperties: false
      properties:
        id: *a10
        tenantId: *a10
        key: *a13
        width:
          type: integer
        height:
          type: integer
        bytes:
          type: integer
        createdAt: *a12
      required:
        - id
        - tenantId
        - key
        - width
        - height
        - bytes
        - createdAt
    Pass:
      type: object
      additionalProperties: false
      properties:
        id: *a10
        tenantId: *a10
        templateId: *a10
        signerId: *a10
        passTypeIdentifier: *a13
        serialNumber: *a10
        installUrl:
          type: string
          format: uri
        tokenExpiresAt:
          anyOf:
            - *a12
            - type: "null"
        variables:
          $ref: "#/components/schemas/Variables"
        status:
          enum:
            - active
            - voided
            - expired
        expirationDate:
          anyOf:
            - *a12
            - type: "null"
        revision:
          type: integer
        views:
          type: integer
        downloads:
          type: integer
        createdAt: *a12
        updatedAt: *a12
        installedCount:
          type: integer
          description: Active device/pass registrations; present on GET by ID only.
      required:
        - id
        - serialNumber
        - installUrl
        - status
        - variables
        - revision
    KeyMetadata:
      type: object
      additionalProperties: false
      properties:
        id: *a10
        label: *a13
        createdAt: *a12
        revokedAt:
          anyOf:
            - *a12
            - type: "null"
      required:
        - id
        - label
        - createdAt
        - revokedAt
    SignerInput:
      type: object
      additionalProperties: false
      properties:
        passTypeIdentifier:
          type: string
          pattern: ^pass\.[A-Za-z0-9.-]+$
        teamIdentifier:
          type: string
          pattern: ^[A-Z0-9]{10}$
        signerCert:
          type: string
          description: PEM Pass Type certificate
        signerKey:
          type: string
          description: PEM private key
        signerKeyPassphrase: *a13
        wwdr:
          type: string
          description: PEM matching Apple WWDR intermediate
      required:
        - passTypeIdentifier
        - teamIdentifier
        - signerCert
        - signerKey
        - wwdr
    Webhook:
      type: object
      additionalProperties: false
      properties:
        id: *a10
        url:
          type: string
          format: uri
        enabled:
          type: boolean
        createdAt: *a12
      required:
        - id
        - url
        - enabled
        - createdAt
    WebhookEvent:
      type: object
      additionalProperties: false
      properties:
        id: *a10
        type:
          enum:
            - pass.installed
            - pass.removed
            - pass.viewed
        createdAt: *a12
        data:
          type: object
          additionalProperties: false
          properties:
            passId: *a10
          required:
            - passId
      required:
        - id
        - type
        - createdAt
        - data
