Cotal
DocsAPI Reference

Verify a managed agent host decision

POST
/manager-service-authority/verify-enrollment

Verify enrollment, retirement preparation, runtime creation or runtime status. Forward the participant request verbatim. The host derives the interactive actor scope from its own ledger; the caller cannot supply scope.

Authorization

HostCapability
headerAuthorizationBearer <token>

Exact exchange capability from the owner-private auth-service discovery record. This is not an IdP JWT or actor bearer.

Request Body

application/json
  1. body
owner*string
Match^u_[a-z2-7]{26}$
request*|||

Native requests from packages/core/src/remote-manager-authority.ts. Forward verbatim; the host derives caller scope from its ledger.

Response Body

The host decision completed.

application/json
  1. response
authorized*unknown
owner*string
Match^u_[a-z2-7]{26}$
actor*string
Match^[A-Za-z0-9_]+$
Length1 <= length
instanceId*string
Match^[a-z0-9]{26,32}$
serveEpoch*integer
Example Request
curl -X POST 'http://127.0.0.1:12345/manager-service-authority/verify-enrollment' \  -H 'Content-Type: application/json' \  -d '{  "owner": "string",  "request": {    "v": 1,    "kind": "manager-managed-agent-enrollment",    "space": "string",    "actor": "string",    "instanceId": "string",    "managerLifecycleUid": "string",    "requestId": "string",    "registrationProof": "string",    "serveEpoch": 0,    "target": {      "actor": "string",      "tokenHash": "string"    },    "identities": {      "supervisor": {        "id": "string"      },      "executor": {        "id": "string"      },      "serve": {        "id": "string"      },      "goalWriter": {        "id": "string"      },      "sessionLedger": {        "id": "string"      }    }  }}'
Example Response
{  "authorized": true,  "owner": "string",  "actor": "string",  "instanceId": "string",  "serveEpoch": 0}

See the HTTP interface overview for authentication and access requirements.

Complete HTTP contract

Endpoint

POST /manager-service-authority/verify-enrollment

Verify enrollment, retirement preparation, runtime creation or runtime status. Forward the participant request verbatim. The host derives the interactive actor scope from its own ledger; the caller cannot supply scope.

Parameters

No operation parameters.

Request body

The request uses the schema below.

Required: yes.

Content type: application/json.

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "pattern": "^u_[a-z2-7]{26}$"
    },
    "request": {
      "$ref": "#/components/schemas/ManagedDecisionRequest"
    }
  },
  "required": [
    "owner",
    "request"
  ],
  "additionalProperties": false
}

Responses

HTTP 200

The host decision completed.

Content type: application/json.

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "authorized": {
          "const": true
        },
        "owner": {
          "type": "string",
          "pattern": "^u_[a-z2-7]{26}$"
        },
        "actor": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_]+$",
          "minLength": 1
        },
        "instanceId": {
          "type": "string",
          "pattern": "^[a-z0-9]{26,32}$"
        },
        "serveEpoch": {
          "type": "integer"
        }
      },
      "required": [
        "authorized",
        "owner",
        "actor",
        "instanceId",
        "serveEpoch"
      ]
    },
    {
      "type": "object",
      "properties": {
        "authorized": {
          "const": true
        },
        "v": {
          "const": 1
        },
        "kind": {
          "type": "string",
          "enum": [
            "manager-managed-agent-runtime-create",
            "manager-managed-agent-runtime-status"
          ]
        },
        "space": {
          "type": "string"
        },
        "owner": {
          "type": "string",
          "pattern": "^u_[a-z2-7]{26}$"
        },
        "actor": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_]+$",
          "minLength": 1
        },
        "instanceId": {
          "type": "string",
          "pattern": "^[a-z0-9]{26,32}$"
        },
        "managerLifecycleUid": {
          "type": "string",
          "pattern": "^[a-z0-9]{26,32}$"
        },
        "requestId": {
          "type": "string"
        },
        "target": {
          "$ref": "#/components/schemas/LifecycleTarget"
        },
        "state": {
          "type": "string",
          "enum": [
            "reserved",
            "creating",
            "bound",
            "create-unknown",
            "closing",
            "closed"
          ]
        },
        "readiness": {
          "type": "string",
          "enum": [
            "ready",
            "bound-not-ready",
            "none"
          ]
        },
        "retirementPhase": {
          "type": "string",
          "enum": [
            "intent",
            "released",
            "retired",
            "deprovisioned",
            "terminal"
          ]
        }
      },
      "required": [
        "authorized",
        "v",
        "kind",
        "space",
        "owner",
        "actor",
        "instanceId",
        "managerLifecycleUid",
        "requestId",
        "target",
        "state",
        "readiness"
      ]
    }
  ]
}

HTTP 400

Malformed JSON or invalid request fields.

Content type: application/json.

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

HTTP 401

Missing or invalid loopback capability.

Content type: application/json.

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

HTTP 403

An Origin header or failed authority/proof check is refused.

Content type: application/json.

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

HTTP 405

Only POST is accepted.

Content type: application/json.

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

HTTP 409

Native conflict.

Content type: application/json.

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

HTTP 412

Native failed precondition.

Content type: application/json.

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

HTTP 413

Request exceeds the 65536-byte body limit.

Content type: application/json.

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

HTTP 415

Content-Type must be application/json.

Content type: application/json.

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

HTTP 429

Invalid-capability attempts exceeded the rolling-minute limit.

Content type: application/json.

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

Authentication and access: Host-only HTTP operations of the stock auth service. These six routes exist only on the loopback listener and return 404 on the public listener. The owner-private auth-service discovery record supplies its port and exchange capability. Every operation requires the exact Authorization bearer capability, application/json and no Origin header. Requests match the exact target, so query strings and trailing slashes return 404. Bodies default to 65536 bytes. More than 30 invalid capability attempts in a rolling minute receive 429.

The loopback listener also serves /health, /jwks, /exchange, /manager-service-authority, /manager-instances, /service-endpoint-authority, /service-endpoint-host and /chat-session/open, /chat-session/bearer, /chat-session/retire. Their public request and response shapes are in the Auth HTTP API. Proof operations additionally require the loopback capability. The loopback /health handler also accepts other methods. Elevated exchange views and operator host operations are loopback-only. Mesh discovery is public-listener-only. This implementation reference does not establish a stable cloud API.

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

Retire managed POST

Retire a managed lifecycle

Verify human proof POST

Verify a fresh human proof