MandateShield Account execution control API

openapi: 3.2.0
info:
  title: MandateShield Payment Authority Account execution control…
  version: 3.4.0
  description: Fail-closed authority verification, provider-bound execution permits and provider-outcome reconciliation that is caller-report-independent for autonomous AI-agent purchases.
  termsOfService: https://mandateshield.com/terms
  contact:
    name: Gökhan Vodinali · MandateShield operator
    url: https://mandateshield.com/legal
    email: support@hemelion.com
servers:
- url: https://mandateshield.com
tags:
- name: Account execution control
  description: Hosting-authenticated account-owner emergency control. The interlock governs new MandateShield-mediated strict operations inside one account regardless of provider profile. It cannot stop customer infrastructure that bypasses MandateShield or recall a step that committed before PAUSE.
  externalDocs:
    url: https://mandateshield.com/specifications/global-execution-interlock/v1
paths:
  /api/account/execution-interlock:
    get:
      operationId: getGlobalExecutionInterlock
      tags:
      - Account execution control
      summary: Read the account-wide MandateShield execution interlock
      description: Requires the hosting-authenticated account-owner session. Missing or corrupt control state is returned as PAUSED with integrity=FAIL_CLOSED; it never silently means RUNNING.
      security:
      - hostingSession: []
      responses:
        '200':
          description: Current effective interlock state
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - interlock
                properties:
                  interlock:
                    $ref: '#/components/schemas/ExecutionInterlockStatus'
        '401':
          description: A hosting-authenticated account-owner session is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: setGlobalExecutionInterlock
      tags:
      - Account execution control
      summary: Atomically PAUSE or RESUME new account-wide execution
      description: Requires a trusted same-origin request and the hosting-authenticated account-owner session. PAUSE remains available without current legal acceptance. RESUME requires current legal acceptance. expected_generation prevents a stale RESUME from overriding a newer PAUSE. After PAUSE commits, new strict reservations, PROCESSOR CONSUME and execution-permit redemption fail closed; receipt verification, outcome reporting and reconciliation remain available.
      security:
      - hostingSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionInterlockMutation'
            examples:
              pause:
                value:
                  action: PAUSE
                  expected_generation: 3
              resume:
                value:
                  action: RESUME
                  expected_generation: 4
      responses:
        '200':
          description: Transition committed or the requested state was already effective
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - interlock
                properties:
                  interlock:
                    $ref: '#/components/schemas/ExecutionInterlockMutationStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: A hosting-authenticated account-owner session is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The control-plane origin is not trusted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The expected generation is stale; no transition was applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '428':
          description: Current legal acceptance is required for RESUME
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The state transition could not be verified; execution remains fail-closed when uncertain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type: string
        enforcement_authorized:
          type: boolean
    ExecutionInterlockStatus:
      type: object
      additionalProperties: false
      required:
      - contract
      - state
      - execution_allowed
      - integrity
      - generation
      - last_event_id
      - changed_at
      - paused_at
      - blocked_when_paused
      - remains_available
      - scope
      - limitation
      properties:
        contract:
          type: string
          format: uri
          const: https://mandateshield.com/specifications/global-execution-interlock/v1
        state:
          type: string
          enum:
          - RUNNING
          - PAUSED
        execution_allowed:
          type: boolean
        integrity:
          type: string
          enum:
          - VERIFIED
          - FAIL_CLOSED
        generation:
          type:
          - integer
          - 'null'
          minimum: 0
        last_event_id:
          type:
          - string
          - 'null'
        changed_at:
          type:
          - string
          - 'null'
          format: date-time
        paused_at:
          type:
          - string
          - 'null'
          format: date-time
        blocked_when_paused:
          type: array
          prefixItems:
          - const: STRICT_RESERVATION
          - const: PROCESSOR_CONSUME
          - const: EXECUTION_PERMIT_REDEMPTION
          minItems: 3
          maxItems: 3
        remains_available:
          type: array
          prefixItems:
          - const: RECEIPT_VERIFICATION
          - const: OUTCOME_REPORTING
          - const: RECONCILIATION
          minItems: 3
          maxItems: 3
        scope:
          const: ACCOUNT_WIDE_MANDATESHIELD_MEDIATED
        limitation:
          type: string
    ExecutionInterlockMutation:
      type: object
      additionalProperties: false
      required:
      - action
      - expected_generation
      properties:
        action:
          type: string
          enum:
          - PAUSE
          - RESUME
        expected_generation:
          type: integer
          minimum: 0
    ExecutionInterlockMutationStatus:
      type: object
      additionalProperties: false
      required:
      - contract
      - state
      - execution_allowed
      - integrity
      - generation
      - last_event_id
      - changed_at
      - paused_at
      - blocked_when_paused
      - remains_available
      - scope
      - limitation
      - changed
      - already_effective
      properties:
        contract:
          type: string
          format: uri
          const: https://mandateshield.com/specifications/global-execution-interlock/v1
        state:
          type: string
          enum:
          - RUNNING
          - PAUSED
        execution_allowed:
          type: boolean
        integrity:
          type: string
          enum:
          - VERIFIED
          - FAIL_CLOSED
        generation:
          type:
          - integer
          - 'null'
          minimum: 0
        last_event_id:
          type:
          - string
          - 'null'
        changed_at:
          type:
          - string
          - 'null'
          format: date-time
        paused_at:
          type:
          - string
          - 'null'
          format: date-time
        blocked_when_paused:
          type: array
          prefixItems:
          - const: STRICT_RESERVATION
          - const: PROCESSOR_CONSUME
          - const: EXECUTION_PERMIT_REDEMPTION
          minItems: 3
          maxItems: 3
        remains_available:
          type: array
          prefixItems:
          - const: RECEIPT_VERIFICATION
          - const: OUTCOME_REPORTING
          - const: RECONCILIATION
          minItems: 3
          maxItems: 3
        scope:
          const: ACCOUNT_WIDE_MANDATESHIELD_MEDIATED
        limitation:
          type: string
        changed:
          type: boolean
        already_effective:
          type: boolean
  responses:
    BadRequest:
      description: Invalid JSON, shape or parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    hostingSession:
      type: apiKey
      in: header
      name: OAI-Authenticated-User-Email
      description: Hosting-injected authenticated account-owner identity. The hosting boundary validates the user session and injects this assertion; callers cannot authenticate by supplying this header directly. State-changing control-plane requests additionally require the trusted same-origin check documented by the operation.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ms_test_… or ms_live_…
      description: Keep API keys server-side and isolate them by purpose. VERIFY keys can issue challenges and strict decisions. Paid live PROCESSOR keys are bound to one processor_audience and can call only the execution-transition boundary.
x-mandateshield-release:
  product_version: 1.13.0
  openapi_version: 3.4.0
  standard_version: 2.4.0
  released_at: '2026-07-28T14:25:22.000Z'
  generated_at: '2026-07-28T14:25:22.000Z'
  status: current
  latest_pointer: https://mandateshield.com/current-release.json
  superseded_by: null
  canonical_versioned_documents:
    openapi: https://mandateshield.com/openapi/3.4.0.json
    llms: https://mandateshield.com/llms/1.13.0.txt
    llms_full: https://mandateshield.com/llms-full/1.13.0.txt
    discovery: https://mandateshield.com/discovery/1.13.0.json