{
  "openapi": "3.0.3",
  "info": {
    "title": "SecuMailer Public API - Account",
    "version": "1.1.1"
  },
  "servers": [
    {
      "url": "https://api.secumail.nl",
      "description": "Production - SecumailPrivateAPI-PRD, stage prd"
    },
    {
      "url": "https://test-api.secumail.nl",
      "description": "Acceptance - SecumailPrivateAPI-ACC, stage acc"
    }
  ],
  "tags": [
    {
      "name": "Reseller",
      "description": "Third-party domain onboarding."
    }
  ],
  "paths": {
    "/reseller/account": {
      "post": {
        "tags": [
          "Reseller"
        ],
        "summary": "Onboard a customer domain (third-party resellers)",
        "description": "**This is the endpoint for third-party resellers.** Authenticate with\nthe OAuth 2.0 client-credentials grant and send the resulting access\ntoken - see the security scheme.\n\n```json\n{\n  \"domain\":  \"<domain>\",\n  \"user\":    \"<user>\",\n  \"org\":     \"<org>\",\n  \"prefix\":  \"secumailer\",\n  \"contact\": \"secumailer\"\n}\n```\n\n`prefix` and `contact` are **hard-coded server-side** and are not taken\nfrom the request body.",
        "operationId": "createResellerAccount",
        "requestBody": {
          "description": "Onboarding request.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal accepted payload",
                  "description": "The three attributes the backend actually requires.",
                  "value": {
                    "domain": "example.nl",
                    "user": "info@example.nl",
                    "org": "Example B.V."
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "**The success status is `201`, not `200`.** The method declares\n`201`, `400` and `500` and no `200` at all. A client that treats\nonly `200` as success will misread every successful call.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountResponse"
                },
                "examples": {
                  "accepted": {
                    "value": {
                      "domain": "example.nl"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body was absent, could not be parsed, carried no\nattributes at all, or a mandatory attribute (`domain`, `user`,\n`org`) was absent or empty. `errorMessage` names the offending\nattribute, or the body itself.\n\nProduced by the method's `.*\\[Bad Request\\].*` integration\nresponse. Verified live on acceptance.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missingAttribute": {
                    "summary": "Mandatory attribute absent",
                    "value": {
                      "errorMessage": "[Bad Request] org attribute is mandatory",
                      "errorType": "Exception"
                    }
                  },
                  "emptyAttribute": {
                    "summary": "Mandatory attribute present but empty",
                    "value": {
                      "errorMessage": "[Bad Request] domain attribute is empty",
                      "errorType": "Exception"
                    }
                  },
                  "missingBody": {
                    "summary": "Body absent or not parseable into `body-json`",
                    "value": {
                      "errorMessage": "[Bad Request] Request body is missing",
                      "errorType": "Exception"
                    }
                  },
                  "emptyBody": {
                    "summary": "Body parsed into `body-json` but carried no attributes",
                    "value": {
                      "errorMessage": "[Bad Request] Request body is empty",
                      "errorType": "Exception"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "examples": {
                  "unauthenticated": {
                    "value": {
                      "message": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Authenticated but not permitted: a WAF block, a resource-policy\ndenial, or - on `/reseller/account` - a token whose `scope` claim\ndoes not include the scope the method requires.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "message": "Forbidden"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "examples": {
                  "unsupportedMediaType": {
                    "value": {
                      "message": "Unsupported Media Type"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "* production - `api.secumail.nl`, stage `prd`: 100 requests/second\n  sustained, 500 burst\n* acceptance - `test-api.secumail.nl`, stage `acc`: 10\n  requests/second sustained, 50 burst\n\nNeither stage configures a quota, so `QUOTA_EXCEEDED` does not\narise. A `429` here is always a rate or burst breach.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "examples": {
                  "throttled": {
                    "value": {
                      "message": "Too Many Requests"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "stepFailed": {
                    "value": {
                      "errorType": "Exception"
                    }
                  }
                }
              }
            }
          },
          "504": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [
              "default-m2m-resource-server-30pyuc/read"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AccountRequest": {
        "title": "Domain",
        "required": [
          "domain",
          "org",
          "user"
        ],
        "type": "object",
        "properties": {
          "domain": {
            "minLength": 1,
            "type": "string",
            "description": "The customer domain to onboard, without scheme or trailing dot. Echoed back in the response.",
            "example": "example.nl"
          },
          "user": {
            "minLength": 1,
            "type": "string",
            "description": "E-mail address of the primary administrative user for the new account.",
            "example": "info@example.nl"
          },
          "org": {
            "minLength": 1,
            "type": "string",
            "description": "Display name of the organisation owning the domain.",
            "example": "Example B.V."
          },
          "domainUser": {
            "type": "string",
            "description": "Accepted by the production request model but **ignored** by the backend - never read from the body, never forwarded to the onboarding workflow. Retained for backwards compatibility.",
            "example": "admin@example.nl",
            "deprecated": true
          },
          "prefix": {
            "type": "string",
            "description": "Accepted by the production request model but **ignored** by the backend. The value forwarded to the onboarding workflow is hard-coded to `secumailer` regardless of what is sent.",
            "example": "secumailer",
            "deprecated": true
          }
        },
        "additionalProperties": true,
        "description": "Onboarding payload. Identical for both endpoints.\n\n**Note on `required`:** the `Domain` JSON Schema model registered on\nthe production `/account` method marks only `domain` as required, and\nneither API attaches a request validator, so the model is never\nenforced at the gateway at all. The backend rejects a payload with a\nmissing or empty `user` or `org` with `400`. This specification\ndocuments the effective contract - all three are mandatory in practice.\n\nAll three string attributes are passed through\n`filter_var(..., FILTER_SANITIZE_SPECIAL_CHARS)` server-side, so\n`<`, `>`, `&`, `\"` and `'` are HTML-encoded before they reach the\nonboarding workflow. There is no format validation: `domain` is not\nchecked against a hostname pattern and `user` is not checked against an\ne-mail pattern.\n\n**Unknown attributes are accepted and ignored.** The backend reads only\nthe attributes named here and never rejects a payload for carrying\nothers, so this schema is deliberately open. A generated client or a\nvalidating proxy must not reject a body on the strength of an\nunrecognised key - doing so would refuse payloads the API accepts."
      },
      "AccountResponse": {
        "title": "AccountAccepted",
        "required": [
          "domain"
        ],
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "The sanitised domain that was submitted to the onboarding workflow.",
            "example": "example.nl"
          }
        },
        "description": "Acknowledgement that the onboarding execution was started.\n\nThe `400` and `500` responses *do* carry a mapping template as of\n2026-09-08, so this caveat applies to the success response only."
      },
      "Error": {
        "title": "BackendError",
        "type": "object",
        "properties": {
          "errorMessage": {
            "type": "string",
            "example": "[Bad Request] org attribute is mandatory"
          },
          "errorType": {
            "type": "string",
            "example": "Exception"
          }
        },
        "additionalProperties": true
      },
      "GatewayError": {
        "title": "GatewayError",
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Forbidden"
          }
        },
        "additionalProperties": true
      }
    },
    "headers": {
      "AccessControlAllowOrigin": {
        "required": false,
        "schema": {
          "type": "string",
          "example": "*"
        }
      }
    },
    "securitySchemes": {
      "OAuth2ClientCredentials": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials (access token in the Authorization header)."
      }
    }
  },
  "security": []
}