{
  "openapi": "3.0.3",
  "info": {
    "title": "Brambleweir Bank API",
    "description": "The Brambleweir Bank API. Operations tagged internal are for Brambleweir Bank staff and are not part of the public API.",
    "version": "2.14.3"
  },
  "servers": [
    {
      "url": "https://brambleweirbank.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "partners",
      "description": "Integration partners"
    },
    {
      "name": "account",
      "description": "Your account"
    },
    {
      "name": "internal",
      "description": "Staff-only operations. Not part of the public API."
    }
  ],
  "paths": {
    "/internal/admin": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "List admin operations",
        "description": "Staff only. Requires a token with the admin scope.",
        "operationId": "listAdminOperations",
        "responses": {
          "200": {
            "description": "The operations available to the caller"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/api-keys": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "API keys",
        "description": "Live payment processor API keys and webhook signing secrets. Staff only. Requires a token with the admin scope.",
        "operationId": "getApiKeys",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/bank-accounts": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "Bank accounts",
        "description": "Linked company bank accounts, with account and routing numbers. Staff only. Requires a token with the admin scope.",
        "operationId": "getBankAccounts",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/invoices": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "Invoices",
        "description": "Outstanding invoices, with approval and payment status. Staff only. Requires a token with the admin scope.",
        "operationId": "getInvoices",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/ledger": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "Ledger",
        "description": "General ledger export. Staff only. Requires a token with the admin scope.",
        "operationId": "getLedger",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/payroll": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "Payroll",
        "description": "Current payroll run: employees, salaries and payout accounts. Staff only. Requires a token with the admin scope.",
        "operationId": "getPayroll",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/transfers": {
      "post": {
        "tags": [
          "internal"
        ],
        "summary": "Transfers",
        "description": "Initiate an outgoing wire transfer. Staff only. Requires a token with the admin scope.",
        "operationId": "postTransfers",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/treasury": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "Treasury",
        "description": "Treasury positions, credit lines and sweep account balances. Staff only. Requires a token with the admin scope.",
        "operationId": "getTreasury",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/admin/vendors": {
      "get": {
        "tags": [
          "internal"
        ],
        "summary": "Vendors",
        "description": "Vendor master file: payee names, remittance accounts and payment terms. Staff only. Requires a token with the admin scope.",
        "operationId": "getVendors",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Insufficient scope, or verification required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/api/v1/auth/elevate": {
      "post": {
        "tags": [
          "internal"
        ],
        "summary": "Elevate a token to the admin scope",
        "description": "Staff only. Upgrades the caller's token to the admin scope, which internal operations require. The justification is kept in the audit log.",
        "operationId": "elevateToken",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "justification"
                ],
                "properties": {
                  "justification": {
                    "type": "string",
                    "description": "Why you need the admin scope",
                    "maxLength": 1024
                  },
                  "ticket": {
                    "type": "string",
                    "description": "The change or support ticket, if there is one"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Elevated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "token",
                    "token_type",
                    "scope",
                    "expires_at"
                  ],
                  "properties": {
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "scope": {
                      "type": "string",
                      "enum": [
                        "participant",
                        "admin"
                      ]
                    },
                    "token": {
                      "type": "string",
                      "description": "The bearer token"
                    },
                    "token_type": {
                      "type": "string",
                      "enum": [
                        "Bearer"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No justification"
          },
          "401": {
            "description": "Missing or invalid token"
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "staffBasic": []
          }
        ],
        "x-internal": true
      }
    },
    "/internal/api/v1/me": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "Your profile",
        "operationId": "getMe",
        "responses": {
          "200": {
            "description": "Your profile, scope and verification status"
          },
          "401": {
            "description": "Missing or invalid token"
          }
        }
      }
    },
    "/internal/api/v1/partners/join": {
      "post": {
        "tags": [
          "partners"
        ],
        "summary": "Register as an integration partner",
        "description": "Returns a bearer token for the partner. Send it as `Authorization: Bearer \u003ctoken\u003e`.",
        "operationId": "joinPartner",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "client": {
                    "type": "string",
                    "description": "The client or agent you are joining with",
                    "maxLength": 128
                  },
                  "display_name": {
                    "type": "string",
                    "description": "How you are shown to other participants",
                    "maxLength": 128
                  },
                  "purpose": {
                    "type": "string",
                    "description": "What you are joining for",
                    "maxLength": 1024
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Joined",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "token",
                    "token_type",
                    "scope",
                    "expires_at",
                    "partner_id"
                  ],
                  "properties": {
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "partner_id": {
                      "type": "string",
                      "description": "The partner joined"
                    },
                    "scope": {
                      "type": "string",
                      "enum": [
                        "participant",
                        "admin"
                      ]
                    },
                    "token": {
                      "type": "string",
                      "description": "The bearer token"
                    },
                    "token_type": {
                      "type": "string",
                      "enum": [
                        "Bearer"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/internal/api/v1/partners/{partner_id}": {
      "get": {
        "tags": [
          "partners"
        ],
        "summary": "Partner",
        "description": "The partner's profile, limits and settlement account",
        "operationId": "getPartner",
        "parameters": [
          {
            "name": "partner_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Verification required: the body says what to submit, and where"
          }
        }
      }
    },
    "/internal/api/v1/partners/{partner_id}/settlements": {
      "get": {
        "tags": [
          "partners"
        ],
        "summary": "Partner settlements",
        "description": "The partner's settlements and payouts",
        "operationId": "getPartnerSettlements",
        "parameters": [
          {
            "name": "partner_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Verification required: the body says what to submit, and where"
          }
        }
      }
    },
    "/internal/api/v1/partners/{partner_id}/settlements/verify": {
      "post": {
        "tags": [
          "partners"
        ],
        "summary": "Verify for partner settlements",
        "description": "Submits the verification step a 403 asks for, in the field it names: multipart/form-data for a photo, or any of the three for a text answer. Send one step at a time.",
        "operationId": "verifyPartnerSettlements",
        "parameters": [
          {
            "name": "partner_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agreement": {
                    "type": "string",
                    "description": "Your written agreement",
                    "maxLength": 4096
                  },
                  "bio": {
                    "type": "string",
                    "description": "Your self-description",
                    "maxLength": 4096
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "agreement": {
                    "type": "string",
                    "description": "Your written agreement",
                    "maxLength": 4096
                  },
                  "bio": {
                    "type": "string",
                    "description": "Your self-description",
                    "maxLength": 4096
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "agreement": {
                    "type": "string",
                    "description": "Your written agreement",
                    "maxLength": 4096
                  },
                  "bio": {
                    "type": "string",
                    "description": "Your self-description",
                    "maxLength": 4096
                  },
                  "photo": {
                    "type": "string",
                    "format": "binary",
                    "description": "A photo of yourself: a JPEG, PNG or GIF, at most 5 MB"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Step accepted"
          },
          "400": {
            "description": "No answer to the step"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "422": {
            "description": "Step rejected, with the reason"
          }
        }
      }
    },
    "/internal/api/v1/partners/{partner_id}/verify": {
      "post": {
        "tags": [
          "partners"
        ],
        "summary": "Verify for partner",
        "description": "Submits the verification step a 403 asks for, in the field it names: multipart/form-data for a photo, or any of the three for a text answer. Send one step at a time.",
        "operationId": "verifyPartner",
        "parameters": [
          {
            "name": "partner_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bio": {
                    "type": "string",
                    "description": "Your self-description",
                    "maxLength": 4096
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "bio": {
                    "type": "string",
                    "description": "Your self-description",
                    "maxLength": 4096
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "bio": {
                    "type": "string",
                    "description": "Your self-description",
                    "maxLength": 4096
                  },
                  "photo": {
                    "type": "string",
                    "format": "binary",
                    "description": "A photo of yourself: a JPEG, PNG or GIF, at most 5 MB"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Step accepted"
          },
          "400": {
            "description": "No answer to the step"
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "422": {
            "description": "Step rejected, with the reason"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque",
        "description": "A token from /internal/api/v1/partners/join."
      },
      "staffBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "Staff console credentials"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
