Submit a native service authority envelope

EndpointCopy Anchor Link

POST /service-endpoint-authority

Only enabled with service endpoints; otherwise 404 before all guards. Fresh JSON proof is verified by kind, never by a loopback capability. Account/space mismatch yields a native denied result. Protocol denials echo coordinates and state=denied: 401 unauthenticated/proof-mismatch; 409 conflict or registration/proposal state; 422 bad-request, closure-invalid, unsupported-runtime or unsupported; 429 resource-exhausted/rate-limited; other authority denials 403. Native envelope/parser errors are plain 400 errors. revoke and describe-view are currently unsupported (422). Transport, 5xx or unknown effects never justify changing the mutation identity. Origin is refused. registered, credential, ready and status answer 200; approval-required and pending answer 202.

ParametersCopy Anchor Link

No operation parameters.

Request bodyCopy Anchor Link

UTF-8 JSON; maximum 2097152 bytes. An Authorization header does not replace the JSON proof.

Required: yes.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceEnvelope"
}

ResponsesCopy Anchor Link

HTTP 200Copy Anchor Link

Successful response.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceResult"
}

HTTP 202Copy Anchor Link

Native approval-required or pending result with echoed coordinates; replay the same request after approval.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceResult"
}

HTTP 400Copy Anchor Link

JSON error from a named request refusal. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401Copy Anchor Link

Native denied result with echoed coordinates, state=denied and reason.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceResult"
}

HTTP 403Copy Anchor Link

Native denied result for account or authority refusal, or a plain error when Origin is present before envelope parsing.

Content type: application/json.

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/ServiceResult"
    },
    {
      "$ref": "#/components/schemas/Error"
    }
  ]
}

HTTP 404Copy Anchor Link

JSON error from a named request refusal. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 405Copy Anchor Link

JSON error from a named request refusal. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 409Copy Anchor Link

Native denied result with echoed coordinates, state=denied and reason.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceResult"
}

HTTP 413Copy Anchor Link

JSON error from a named request refusal. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 415Copy Anchor Link

JSON error from a named request refusal. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 422Copy Anchor Link

Native denied result with echoed coordinates, state=denied and reason.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceResult"
}

HTTP 429Copy Anchor Link

Native denied result with echoed coordinates, state=denied and reason.

Content type: application/json.

{
  "$ref": "#/components/schemas/ServiceResult"
}

HTTP 500Copy Anchor Link

Server failure. An unexpected failure reaching the listener boundary returns only {"error":"internal server error"}; details are logged server-side. A route's named server failure may include its error code and outcome.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

Example:

{
  "error": "internal server error"
}

HTTP 503Copy Anchor Link

Public admission cap (64 in flight), 10 second request deadline, or a route-specific unavailable read/effect. A service authority 503 may follow a binding; retain the request identity.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

Authentication and access: HTTP interface of the stock auth public listener: 11 paths and 12 operations. Public means reachable through the configured listener, not unauthenticated. This implementation surface uses Cotal native contracts and does not establish a stable cloud API. Description version 1.0.0 identifies this document, not the wire or npm package version.

Credentials are JSON body proofs, with no loopback capability required. No CORS headers are sent. All POST routes and service authority GET reject any Origin header. Health, JWKS and mesh discovery GET permit Origin headers.

The listener binds 127.0.0.1; an operator HTTPS proxy supplies the external origin. Service endpoint routes require service endpoints enabled. Route lookup uses the exact request target: query strings and trailing slashes do not match and return JSON 404. Unknown paths and loopback-only lifecycle, enrollment verification, human-proof and consent routes return JSON 404. Configuration and route-specific native parser checks remain authoritative.

POST JSON bodies default to 65536 bytes; service authority accepts 2097152 bytes. Public work has 64 concurrent admissions and a 10000 ms deadline. Its separate rolling 30-refusal/minute peer budget is bounded to 1024 peer entries. Failure accounting is route-specific. Manager dispatch failures and chat native or store failures can consume the budget after valid proof verification. Otherwise successful requests are still evaluated when the refusal budget is full. Peer is socket address unless trusted proxy mode selects the last X-Forwarded-For hop.

OpenAPI specification contains the referenced response schemas. Complete Markdown reference.