{
  "openapi": "3.1.0",
  "info": {
    "title": "NewLedger Partner API",
    "description": "For backend-integrated partners only, not for general API clients. Every operation except the token call needs a partner token (aud=partner, issued by POST /partner/token for a partner credential); App Connect and user tokens are refused, and Core re-checks that the partner owns the company. Covers partner token, tenant provisioning, user management, company listing and usage, suspend/resume, de-provisioning and session minting on partner-owned companies.",
    "termsOfService": "https://newledger.io/terms",
    "contact": {
      "name": "NewLedger Support",
      "url": "https://newledger.io/contact",
      "email": "support@newledger.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://newledger.io/license"
    },
    "version": "1.1.0"
  },
  "paths": {
    "/v1/partner/companies": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "List partner companies",
        "description": "Lists the partner's licensed companies, oldest first, with each company's id, external id and status. Active and suspended companies are listed; de-provisioned companies are not. Paginated by cursor: pass `next_cursor` as `cursor` until it is null. For the partner's total against its company limit, use the usage operation.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "list_companies_get_partner_companies",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Companies per page, 1 to 100. Defaults to 50.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "`next_cursor` from the previous page. Omit for the first page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of companies",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerCompanyListResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Invalid `limit` or `cursor`",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 60 requests per minute per client (bursts up to 80). The response has no body and no `Retry-After` header; wait 1 second before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      },
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Provision companies",
        "description": "Creates up to 100 companies with their owner user through the signup path (no captcha, verification, terms, password, welcome mail, or trial). Idempotent on the partner's external ids: same payload returns the existing rows, a different payload returns 409 for that item. Per-item outcomes.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "provision_companies",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProvisionCompaniesForm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Per-item results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvisionCompaniesResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Partner token required"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/companies/{company_id}": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "Get a partner company",
        "description": "Returns one of the partner's licensed companies: its details, and its user and client counts against the per-company limits under `usage`. The counts are live and match what the limit checks enforce; clients exclude vendors. For looking up one company: to read every company, use the company list, which carries neither details nor counts. A de-provisioned company, or one the partner does not hold, fails with `PARTNER_OWNERSHIP_DENIED`.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "get_company",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "description": "Company id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The company",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerCompanyDetailResponseModel"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "403": {
            "description": "Company not held by this partner"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 60 requests per minute per client (bursts up to 80). The response has no body and no `Retry-After` header; wait 1 second before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/companies/{company_id}/deprovision": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "De-provision a partner company",
        "description": "Permanently ends a suspended company the partner owns and frees its slot in the partner's company limit. A suspended company keeps its slot until this call. The company must be suspended first; otherwise the call fails with `PARTNER_COMPANY_NOT_SUSPENDED`. The company's data is retained but it can no longer be used, and resume, add-user and session calls for it fail with `PARTNER_OWNERSHIP_DENIED`. The same `external_company_id` can be provisioned again as a new company. Safe to repeat.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "deprovision_company",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "description": "Company id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Company de-provisioned; returns the company id and status `deprovisioned`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerActionResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "403": {
            "description": "Company not owned by this partner"
          },
          "409": {
            "description": "Company is not suspended"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/companies/{company_id}/resume": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Resume a suspended partner company",
        "description": "Marks a suspended company the partner owns as active again. Sessions are not restored: mint new ones. Ownership is checked on every call, and the change is recorded in the company's activity log.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "resume_company",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "description": "Company id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Company active again; returns the company id and status `active`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerActionResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "403": {
            "description": "Company not owned by this partner"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/companies/{company_id}/sessions": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Mint user sessions on a partner company",
        "description": "Issues short-lived App Connect access tokens for one or more partner-managed users of a company the partner owns. Ownership (company, user, membership all under the partner) is re-checked on every call; permissions are the user's current role capped by the licence ceiling; a company without a subscription or under a read-only licence receives read-only tokens. Each session token lasts the partner credential's session lifetime (between 300 and 900 seconds, set when the credential is created); the result carries `expires_in` and `expires_at`. Per-user outcomes: a company the partner did not provision, or a user who is not its partner-managed member, fails with `PARTNER_OWNERSHIP_DENIED`; a company the partner suspended fails with `PARTNER_COMPANY_SUSPENDED` until it is resumed.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "mint_sessions",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "description": "Company id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerSessionForm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Per-user results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerSessionsResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Partner token or credential invalid"
          },
          "403": {
            "description": "Partner suspended"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 600 requests per minute per client (bursts up to 700). The response has no body and no `Retry-After` header; wait 0.1 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/companies/{company_id}/suspend": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Suspend a partner company",
        "description": "Marks a company the partner owns as suspended. Session tokens already issued for the company stop working immediately, and minting a new session fails with `PARTNER_COMPANY_SUSPENDED` until the company is resumed. Ownership is checked on every call, and the change is recorded in the company's activity log. Safe to repeat. A suspended company keeps its slot in the partner's company limit; de-provision it to free the slot. Call the resume operation to reverse it.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "suspend_company",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "description": "Company id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Company suspended; returns the company id and status `suspended`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerActionResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "403": {
            "description": "Company not owned by this partner"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/companies/{company_id}/users": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Add a user to a partner company",
        "description": "Adds a partner-managed user with a role from the company's own role list. Portal roles (client, vendor) are refused. Reuses an existing user by external id (one user, many companies).\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "add_user",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "description": "Company id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerUserCreateForm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "User attached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerUserResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Invalid role",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "403": {
            "description": "Company not owned by this partner"
          },
          "409": {
            "description": "Email already exists or limit reached"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/token": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Partner token (client credentials)",
        "description": "The token is valid for 900 seconds (`expires_in`); request a new one when it expires. Issues an `aud=partner` token for a partner credential. Accepted only on `/partner/*` routes. `client_secret_ip` credentials must present the secret from an allow-listed source IP, and every call made with the token must also come from an allow-listed source IP.",
        "operationId": "token",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerTokenForm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Token issued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerTokenResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid client credentials"
          },
          "403": {
            "description": "Partner suspended"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [],
        "x-api-gateway-auth": {
          "bearer": false
        }
      }
    },
    "/v1/partner/usage": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "Partner usage",
        "description": "Returns how many companies the partner holds against its company limit, with a count per status. `used` is active plus suspended; deleted companies do not count toward it, and stay in `by_status.deleted` until they are permanently removed. Provisioning fails with `PARTNER_LIMIT_REACHED` when `companies.used` equals `companies.limit`. Light enough to call often.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "usage",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The partner's usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerUsageResponseModel"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 60 requests per minute per client (bursts up to 80). The response has no body and no `Retry-After` header; wait 1 second before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    },
    "/v1/partner/users/{user_id}/deactivate": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Deactivate a partner-managed user",
        "description": "Deactivates every membership, revokes the user's partner sessions, and marks the user inactive. Session tokens already issued to the user stop working immediately, in every company; minting a new session for the user fails. Safe to repeat: a repeat call revokes any token still live.\n\nThe API Gateway requires a bearer access token. Allowed JWT audiences: partner.",
        "operationId": "deactivate_user",
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "description": "User id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User deactivated; returns the user id and status `deactivated`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerActionResponseModel"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed for one or more fields, or a business rule rejected the request. Field validation returns `{\"error\": {field: [codes]}}`; other rejections return `{\"error\": {code, message, details?}}`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: JWT Bearer token missing or expired."
          },
          "403": {
            "description": "User not owned by this partner"
          },
          "429": {
            "description": "Rate limit exceeded: this operation allows 30 requests per minute per client (bursts up to 40). The response has no body and no `Retry-After` header; wait 2 seconds before retrying."
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred on the server. The body is either the JSON string `INTERNAL_SERVER_ERROR` or the standard `{\"error\": {code, message}}` envelope, depending on the route.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InternalServerErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/UserErrorModel"
                    }
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-api-gateway-auth": {
          "bearer": true,
          "audience": [
            "partner"
          ]
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "PartnerDomain": {
        "name": "x-partner-domain",
        "in": "header",
        "required": true,
        "description": "The domain you registered on, which identifies your partner: for example the production or sandbox host of the platform, or your own registered domain. Calls without it are rejected with HTTP 400, and a domain that is not registered returns HTTP 404 `PARTNER_DOMAIN_NOT_ALLOWED`.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "InternalServerErrorResponse": {
        "type": "string",
        "description": "An unexpected server error, returned as a JSON string. Some operations instead return\nthe standard error envelope; the 500 response schema documents both shapes.",
        "example": "INTERNAL_SERVER_ERROR"
      },
      "PartnerActionModel": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the record."
          },
          "status": {
            "type": "string"
          }
        }
      },
      "PartnerActionResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerActionModel"
          }
        }
      },
      "PartnerCompanyDetailModel": {
        "type": "object",
        "required": [
          "company_id",
          "status",
          "name",
          "currency",
          "timezone",
          "fiscal_year_end",
          "created_at",
          "usage"
        ],
        "properties": {
          "company_id": {
            "type": "string",
            "description": "Company the record belongs to."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the record was created (ISO 8601 timestamp)."
          },
          "currency": {
            "type": "string",
            "description": "The company's base currency, as an ISO 4217 code."
          },
          "external_company_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The partner's own id. Null for a company created through web signup or in-app create."
          },
          "fiscal_year_end": {
            "$ref": "#/components/schemas/PartnerFiscalYearEndModel"
          },
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "status": {
            "type": "string",
            "description": "`active` or `suspended`."
          },
          "timezone": {
            "type": "string",
            "description": "IANA time zone name."
          },
          "usage": {
            "$ref": "#/components/schemas/PartnerCompanyDetailUsageModel"
          }
        }
      },
      "PartnerCompanyDetailResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerCompanyDetailModel"
          }
        }
      },
      "PartnerCompanyDetailUsageModel": {
        "type": "object",
        "required": [
          "users",
          "clients"
        ],
        "properties": {
          "clients": {
            "$ref": "#/components/schemas/PartnerUsageModel",
            "description": "Clients only; vendors are not counted."
          },
          "users": {
            "$ref": "#/components/schemas/PartnerUsageModel"
          }
        }
      },
      "PartnerCompanyListModel": {
        "type": "object",
        "required": [
          "companies"
        ],
        "properties": {
          "companies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerCompanyModel"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `cursor` for the next page. Null on the last page."
          }
        }
      },
      "PartnerCompanyListResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerCompanyListModel"
          }
        }
      },
      "PartnerCompanyModel": {
        "type": "object",
        "required": [
          "company_id",
          "status"
        ],
        "properties": {
          "company_id": {
            "type": "string",
            "description": "Company the record belongs to."
          },
          "external_company_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The partner's own id. Null for a company created through web signup or in-app create."
          },
          "status": {
            "type": "string",
            "description": "`active` or `suspended`."
          }
        }
      },
      "PartnerCompanyStatusCountsModel": {
        "type": "object",
        "required": [
          "active",
          "suspended",
          "deleted"
        ],
        "properties": {
          "active": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "deleted": {
            "type": "integer",
            "format": "int64",
            "description": "De-provisioned or deleted companies still held in the system. They do not\ncount toward `used`, and leave this count when they are permanently removed.",
            "minimum": 0
          },
          "suspended": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "PartnerCompanyUsageModel": {
        "type": "object",
        "required": [
          "used",
          "limit",
          "by_status"
        ],
        "properties": {
          "by_status": {
            "$ref": "#/components/schemas/PartnerCompanyStatusCountsModel"
          },
          "limit": {
            "type": "integer",
            "format": "int32",
            "description": "Zero means none are allowed; there is no unlimited.",
            "minimum": 0
          },
          "used": {
            "type": "integer",
            "format": "int64",
            "description": "Active and suspended companies, the number the company limit enforces.",
            "minimum": 0
          }
        }
      },
      "PartnerFiscalYearEndModel": {
        "type": "object",
        "required": [
          "month",
          "day"
        ],
        "properties": {
          "day": {
            "type": "integer",
            "format": "int32"
          },
          "month": {
            "type": "integer",
            "format": "int32"
          }
        }
      },
      "PartnerSessionForm": {
        "type": "object",
        "description": "Either one user (`user_id` or `external_user_id`) or a batch in `users`.\nA session always names a user; there is no company-only session.",
        "properties": {
          "external_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSessionUserForm"
            }
          }
        }
      },
      "PartnerSessionResultModel": {
        "type": "object",
        "required": [
          "outcome"
        ],
        "properties": {
          "access_token": {
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_code": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "minimum": 0
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expires_in": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64"
          },
          "external_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "outcome": {
            "$ref": "#/components/schemas/SessionOutcome"
          },
          "permissions": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "token_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PartnerSessionUserForm": {
        "type": "object",
        "properties": {
          "external_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PartnerSessionsResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSessionResultModel"
            }
          }
        }
      },
      "PartnerTokenForm": {
        "type": "object",
        "description": "Exchanges partner credentials or assertions for a scoped partner token. This operation does not use App Connect bearer tokens.",
        "required": [
          "client_id"
        ],
        "properties": {
          "client_assertion": {
            "type": [
              "string",
              "null"
            ],
            "description": "RFC 7523 client assertion for `private_key_jwt`."
          },
          "client_id": {
            "type": "string",
            "description": "The partner credential's client id."
          },
          "client_secret": {
            "type": [
              "string",
              "null"
            ],
            "description": "Secret for a `client_secret_ip` credential (the request must also come from an allow-listed\nIP). A `private_key_jwt` credential sends `client_assertion` instead."
          },
          "grant_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "Must be `client_credentials`.",
            "example": "client_credentials"
          }
        }
      },
      "PartnerTokenModel": {
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "partner_id"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer",
            "format": "int64"
          },
          "partner_id": {
            "type": "string"
          },
          "token_type": {
            "type": "string"
          }
        }
      },
      "PartnerTokenResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerTokenModel"
          }
        }
      },
      "PartnerUsageModel": {
        "type": "object",
        "description": "A count against the licence limit it is enforced by.",
        "required": [
          "used",
          "limit"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "format": "int32",
            "description": "Zero means none are allowed; there is no unlimited.",
            "minimum": 0
          },
          "used": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "PartnerUsageResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerUsageSummaryModel"
          }
        }
      },
      "PartnerUsageSummaryModel": {
        "type": "object",
        "required": [
          "companies"
        ],
        "properties": {
          "companies": {
            "$ref": "#/components/schemas/PartnerCompanyUsageModel"
          }
        }
      },
      "PartnerUserCreateForm": {
        "type": "object",
        "description": "Provisions a partner-managed user using the supplied external identity and profile.",
        "required": [
          "external_user_id",
          "email",
          "name",
          "acl_id"
        ],
        "properties": {
          "acl_id": {
            "type": "string",
            "description": "`acl_company_role.id` from the company's own role list. Portal roles\n(client, vendor) are refused."
          },
          "email": {
            "type": "string"
          },
          "external_user_id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Display name."
          }
        }
      },
      "PartnerUserModel": {
        "type": "object",
        "required": [
          "user_id",
          "company_id",
          "outcome"
        ],
        "properties": {
          "company_id": {
            "type": "string",
            "description": "Company the record belongs to."
          },
          "external_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "outcome": {
            "$ref": "#/components/schemas/ProvisionOutcome"
          },
          "user_id": {
            "type": "string"
          }
        }
      },
      "PartnerUserResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerUserModel"
          }
        }
      },
      "ProvisionCompaniesForm": {
        "type": "object",
        "description": "Provisions a bounded batch of companies and their owner details for a partner.",
        "required": [
          "companies"
        ],
        "properties": {
          "companies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProvisionCompanyForm"
            }
          }
        }
      },
      "ProvisionCompaniesResponseModel": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProvisionCompanyResultModel"
            }
          }
        }
      },
      "ProvisionCompanyForm": {
        "type": "object",
        "required": [
          "external_company_id",
          "company_name",
          "country",
          "currency",
          "locale",
          "timezone",
          "owner"
        ],
        "properties": {
          "company_name": {
            "type": "string",
            "description": "Company or business name."
          },
          "company_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217."
          },
          "external_company_id": {
            "type": "string"
          },
          "locale": {
            "type": "string",
            "description": "e.g. `en-US`."
          },
          "owner": {
            "$ref": "#/components/schemas/ProvisionOwnerForm"
          },
          "timezone": {
            "type": "string"
          }
        }
      },
      "ProvisionCompanyResultModel": {
        "type": "object",
        "required": [
          "external_company_id",
          "outcome"
        ],
        "properties": {
          "company_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Company the record belongs to."
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_code": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "minimum": 0
          },
          "external_company_id": {
            "type": "string"
          },
          "outcome": {
            "$ref": "#/components/schemas/ProvisionOutcome"
          },
          "owner_user_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ProvisionOutcome": {
        "type": "string",
        "enum": [
          "created",
          "existing",
          "failed"
        ]
      },
      "ProvisionOwnerForm": {
        "type": "object",
        "required": [
          "external_user_id",
          "email",
          "name"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "external_user_id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Display name."
          }
        }
      },
      "SessionOutcome": {
        "type": "string",
        "enum": [
          "minted",
          "failed"
        ]
      },
      "UserError": {
        "type": "object",
        "description": "Structured details explaining why an API operation was rejected.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32",
            "description": "HTTP status of the response, repeated in the body.",
            "minimum": 0
          },
          "details": {
            "description": "Free-form JSON; keys and values depend on the producing workflow."
          },
          "message": {
            "type": "string",
            "description": "What went wrong. Usually a stable upper-case code such as `INVALID_ISSUE_DATE`; branch on\nit, and translate it for display. Some older operations return a short English sentence."
          }
        }
      },
      "UserErrorModel": {
        "type": "object",
        "description": "An API error containing a stable machine code and optional structured details for the client to translate.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/UserError"
          }
        }
      },
      "ValidationErrorResponse": {
        "type": "object",
        "description": "A validation error response identifying invalid fields and their machine-readable errors.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "description": "Field name mapped to its error codes. Nested fields join their path with underscores,\nincluding list indexes: `items_0_item_id` is `item_id` on the first entry of `items`.",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "propertyNames": {
              "type": "string"
            }
          }
        },
        "example": {
          "error": {
            "item_name": [
              "REQUIRED_FIELD"
            ],
            "unit_price": [
              "MUST_BE_POSITIVE"
            ]
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Partner",
      "description": "For backend-integrated partners only, not for general API clients. Every operation except the token call needs a partner token (aud=partner, issued by POST /partner/token for a partner credential); App Connect and user tokens are refused, and Core re-checks that the partner owns the company. Covers partner token, tenant provisioning, user management, company listing and usage, suspend/resume, de-provisioning and session minting on partner-owned companies."
    }
  ],
  "servers": [
    {
      "url": "https://api.newledger.io",
      "description": "Production (US)"
    }
  ]
}
