CotalSubmit an owner-scoped native host operation
Only enabled with service endpoints; otherwise 404 before method/media/Origin guards. JSON idpToken derives owner and native granter. Caller-supplied granter is rejected. Operator-only operations are refused publicly (403). Native host outcomes, including denied/held/pending/refused, are returned with HTTP 200; inspect state. denied is a point-in-time no-binding observation, while held alone does not prove execution or authority. Native parser failures are 400, unexpected engine failures 500 or 503. Successful engine replies use Cache-Control: no-store. Origin is refused. instance-read returns only the proved owner's selector, and instance-list returns only that owner's native assignments with cursor pagination. Missing and foreign instance reads both answer absent. proposal-list remains unsupported.
UTF-8 JSON; maximum 65536 bytes. An Authorization header does not replace the JSON proof.
application/json- body
Never provide request.granter. The route derives it from idpToken. name-bind, quarantine-restored, admission-open, and revoke causes other than owner-request are loopback operator actions and return 403 publicly; they are excluded from the accepted operation enum.
idpToken*string1 <= lengthrequest*Transport envelope only. Nested native fields and operation-specific constraints are defined by ServiceHostRequest (HTTP omits granter) in the linked source; this schema is not a complete native command contract.
Successful response.
application/json- response
Transport envelope only. Nested native fields and operation-specific constraints are defined by ServiceHostResult in the linked source; this schema is not a complete native command contract.
v*unknownkind*unknownoperation*string"proposal-read""proposal-list""instance-read""instance-list""operation-read""name-read""decide""revoke""caller-policy-read""caller-policy-list""caller-grant""caller-revoke"requestId*string1 <= lengthspace*string1 <= lengthaccountPublicKey*string1 <= lengthstate*string"present""absent""page""approved""refused""retired""granted""revoked""pending""held""denied"reason?stringcurl -X POST 'https://auth.example.invalid/service-endpoint-host' \ -H 'Content-Type: application/json' \ -d '{ "idpToken": "string", "request": { "v": 1, "kind": "service-endpoint-host", "requestId": "string", "operation": "proposal-read", "input": {} }}'{ "v": 1, "kind": "service-endpoint-host", "operation": "proposal-read", "requestId": "string", "space": "string", "accountPublicKey": "string", "reason": "string", "state": "denied"}See the HTTP interface overview for authentication and access requirements.
Complete HTTP contract
Endpoint
POST /service-endpoint-hostOnly enabled with service endpoints; otherwise 404 before method/media/Origin guards. JSON idpToken derives owner and native granter. Caller-supplied granter is rejected. Operator-only operations are refused publicly (403). Native host outcomes, including denied/held/pending/refused, are returned with HTTP 200; inspect state. denied is a point-in-time no-binding observation, while held alone does not prove execution or authority. Native parser failures are 400, unexpected engine failures 500 or 503. Successful engine replies use Cache-Control: no-store. Origin is refused. instance-read returns only the proved owner's selector, and instance-list returns only that owner's native assignments with cursor pagination. Missing and foreign instance reads both answer absent. proposal-list remains unsupported.
Parameters
No operation parameters.
Request body
UTF-8 JSON; maximum 65536 bytes. An Authorization header does not replace the JSON proof.
Required: yes.
Content type: application/json.
{
"$ref": "#/components/schemas/HostRequest"
}Responses
HTTP 200
Successful response.
Content type: application/json.
{
"$ref": "#/components/schemas/HostResult"
}HTTP 400
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 403
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 404
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 405
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 413
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 415
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 429
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 500
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 503
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.