bubblio-dev Approvals API

openapi: 3.2.0
info:
  title: Bubblio Dev Approvals API
  version: 1.0.0
  contact:
    email: bubblio@andresio.com
  description: 'Operations tagged approvals across 2 of this provider''s published API definitions: openapi.yaml, bubblio-dev-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bubblio.dev
  description: Hosted production platform — the canonical host.
- url: https://andresomar95--bubblio-api-serve.modal.run
  description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
tags:
- name: Approvals
  description: The phone-first consent pages' API (bubblio.dev/a/{id} and /approvals).
paths:
  /approvals/a/{approvalId}:
    get:
      tags:
      - Approvals
      summary: The approval page's facts
      description: 'Renders facts and writes NOTHING — link scanners and chat prefetchers GET links,

        so approval acts only on POST after a human gesture. Includes the mandate context

        (#37: `standing` = the live mandate''s remaining budget, `offer` = the checkbox''s

        server-authored terms) and, for connect ceremonies (#38), the connect step''s state.'
      operationId: getApproval
      parameters:
      - $ref: '#/components/parameters/approvalId'
      responses:
        '200':
          description: The approval's facts.
          content:
            application/json:
              schema:
                type: object
                required:
                - approval
                properties:
                  approval:
                    type: object
                    required:
                    - id
                    - code
                    - status
                    - kind
                    - platform
                    - action
                    - args
                    - args_hash
                    - tier
                    - created_at
                    - expires_at
                    properties:
                      id:
                        $ref: '#/components/schemas/ApprovalId'
                      code:
                        type: string
                        description: The short human-checkable code the agent relayed.
                      status:
                        type: string
                        enum:
                        - pending
                        - approved
                        - declined
                        - revoked
                        - expired
                      kind:
                        type: string
                        enum:
                        - action
                        - connect
                      connect:
                        type: object
                        description: Connect ceremonies only.
                        properties:
                          connected:
                            type: boolean
                          login_url:
                            type:
                            - string
                            - 'null'
                            format: uri
                      platform:
                        type: string
                        description: The door's display label.
                      callback_origin:
                        type:
                        - string
                        - 'null'
                        description: The platform's verified callback origin at mint time.
                      action:
                        type: string
                      args:
                        type: object
                      args_hash:
                        type: string
                      amount:
                        type:
                        - string
                        - 'null'
                        description: Display amount for priced actions.
                      agent:
                        type: object
                        properties:
                          presented:
                            type:
                            - string
                            - 'null'
                            description: The claimed Signature-Agent header, verbatim.
                          verified:
                            type: boolean
                            description: Whether Web Bot Auth PROVED the identity.
                          verified_agent:
                            type: string
                            description: The proven origin, present only when verified.
                      tier:
                        type: string
                        enum:
                        - anonymous
                        - keyed
                      created_at:
                        type: string
                        format: date-time
                      expires_at:
                        type: string
                        format: date-time
                      approved_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      mandate:
                        type:
                        - object
                        - 'null'
                        properties:
                          standing:
                            type: object
                            description: The live mandate covering this door, with remaining budget.
                          offer:
                            type: object
                            description: Server-authored terms the checkbox would mint.
        '404':
          $ref: '#/components/responses/ApprovalMiss'
        '429':
          $ref: '#/components/responses/TooMany'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/a/{approvalId}/options:
    post:
      tags:
      - Approvals
      summary: Mint the WebAuthn ceremony options
      description: 'mode `auth` (returning human: one passkey assertion) or `register` (the first

        FaceID: enrollment IS the approval). Both carry the SAME deterministic challenge —

        the SHA-256 of this approval''s canonical terms — so whichever ceremony runs, the

        signature covers exactly what is being approved. A connect ceremony refuses to mint

        options until its grant holds the platform-minted key.'
      operationId: postApprovalOptions
      parameters:
      - $ref: '#/components/parameters/approvalId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mode
              properties:
                mode:
                  type: string
                  enum:
                  - auth
                  - register
      responses:
        '200':
          description: WebAuthn creation/request options for the browser ceremony.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/CalmBadRequest'
        '404':
          $ref: '#/components/responses/ApprovalMiss'
        '409':
          description: 'Already decided/expired, or the connect gate is not yet connected (`code: not_connected`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
        '429':
          $ref: '#/components/responses/TooMany'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/a/{approvalId}/approve:
    post:
      tags:
      - Approvals
      summary: Approve — the human's passkey signature over the exact terms
      description: 'Verifies the WebAuthn response against the terms-derived challenge and flips the

        approval (winner-only). `mandate: true` additionally mints the offered standing

        mandate — the ceremony and the grant are ONE signature, indivisible. Idempotent:

        re-approving an approved approval answers `{ ok, status: approved, already: true }`.'
      operationId: postApprovalApprove
      parameters:
      - $ref: '#/components/parameters/approvalId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mode
              - credential
              properties:
                mode:
                  type: string
                  enum:
                  - auth
                  - register
                credential:
                  type: object
                  description: The WebAuthn registration/authentication response JSON.
                mandate:
                  type: boolean
                  description: Also mint the offered standing mandate (#37).
      responses:
        '200':
          description: Approved (or already approved).
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                  already:
                    type: boolean
        '400':
          $ref: '#/components/responses/CalmBadRequest'
        '404':
          $ref: '#/components/responses/ApprovalMiss'
        '409':
          description: 'Decided/expired, or the connect gate refused (`code: not_connected`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
        '429':
          $ref: '#/components/responses/TooMany'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/a/{approvalId}/decline:
    post:
      tags:
      - Approvals
      summary: Decline (no ceremony needed — declining must always be easy)
      operationId: postApprovalDecline
      parameters:
      - $ref: '#/components/parameters/approvalId'
      responses:
        '200':
          description: Declined (idempotently).
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                    const: declined
                  already:
                    type: boolean
        '404':
          $ref: '#/components/responses/ApprovalMiss'
        '409':
          description: Already decided in another direction, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
        '429':
          $ref: '#/components/responses/TooMany'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/session/options:
    post:
      tags:
      - Approvals
      summary: Mint a passkey sign-in challenge for the management surface
      description: Random single-use challenge (authentication, not consent-over-terms), 5-minute TTL.
      operationId: postSessionOptions
      responses:
        '200':
          description: WebAuthn request options.
          content:
            application/json:
              schema:
                type: object
                properties:
                  options:
                    type: object
                    properties:
                      challenge:
                        type: string
                      rpId:
                        type: string
                      timeout:
                        type: integer
                      userVerification:
                        type: string
                      allowCredentials:
                        type: array
        '429':
          $ref: '#/components/responses/TooMany'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/session:
    post:
      tags:
      - Approvals
      summary: Verify the sign-in assertion → consent token
      operationId: postSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - credential
              properties:
                credential:
                  type: object
                  description: The WebAuthn authentication response JSON.
      responses:
        '200':
          description: The Bearer token for /approvals/mine.
          content:
            application/json:
              schema:
                type: object
                required:
                - token
                properties:
                  token:
                    type: string
        '400':
          $ref: '#/components/responses/CalmBadRequest'
        '429':
          $ref: '#/components/responses/TooMany'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/mine:
    get:
      tags:
      - Approvals
      summary: Everything this passkey decided — the out-of-band kill-switch surface
      description: Connections, approval receipts, and standing mandates. Works WITHOUT any agent nearby.
      operationId: getMine
      security:
      - consentToken: []
      responses:
        '200':
          description: The passkey's approvals + mandates (display metadata; degraded halves become empty lists, never page failures).
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Sign in with your passkey first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/mine/{approvalId}/revoke:
    post:
      tags:
      - Approvals
      summary: Revoke an approved connection
      description: Winner-only approved → revoked; effective at the very next quote/confirm (the door re-reads live, fail-closed). Idempotent.
      operationId: postRevokeApproval
      security:
      - consentToken: []
      parameters:
      - $ref: '#/components/parameters/approvalId'
      responses:
        '200':
          description: Revoked (or already revoked).
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                  already:
                    type: boolean
        '401':
          description: No consent session.
        '404':
          $ref: '#/components/responses/ApprovalMiss'
        '409':
          description: Only an approved connection can be revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /approvals/mine/mandates/{mandateId}/revoke:
    post:
      tags:
      - Approvals
      summary: Revoke a standing mandate (#37's one-tap kill-switch)
      description: 'Winner-only active → revoked. Immediate at the door: the next quote skips the dead

        mandate, and a confirm on a quote it covered re-reads it LIVE pre-flight and

        refuses without consuming. Idempotent for already-dead mandates.'
      operationId: postRevokeMandate
      security:
      - consentToken: []
      parameters:
      - name: mandateId
        in: path
        required: true
        schema:
          type: string
          pattern: ^mnd_[a-f0-9]{32}$
      responses:
        '200':
          description: 'Revoked (or already in a terminal state, echoed with `already: true`).'
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                  already:
                    type: boolean
        '401':
          description: No consent session.
        '404':
          description: Uniform miss.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
components:
  responses:
    CalmBadRequest:
      description: One calm sentence naming the malformed field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CalmError'
    ApprovalMiss:
      description: 'UNIFORM: unknown, malformed, foreign, and lagged approvals all read the same.'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                const: No approval here.
    TooMany:
      description: Per-IP ceiling tripped.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CalmError'
  schemas:
    CalmError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type: string
          description: Machine-readable refusal code, present where documented — branch on this, never on message text.
    ApprovalId:
      type: string
      pattern: ^apr_[a-f0-9]{32}$
  parameters:
    approvalId:
      name: approvalId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ApprovalId'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: The platform's Bubblio API key (`bbl_…`). Server-side only.
    consentToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The human's passkey-session token from `POST /approvals/session`.
x-refined-from:
- openapi.yaml
- bubblio-dev-openapi.yaml