{
  "category": "zero-human agent onboarding",
  "summary": "How an AI agent discovers Presence, verifies a Presence Record offline with no account, hands the one human step (a verified mailbox provisions the sandbox tenant) to its operator, and then holds actions until a named person approves them — over the API or as an MCP server.",
  "canonical_url": "https://presence.decionis.com/reference/agent-onboarding",
  "audience": "AI agents onboarding themselves. Steps 0–1 need no human and no credential; step 2 is the line the agent surfaces to its operator; steps 3–5 run with the tenant key the operator holds.",
  "human_boundary": {
    "step": 2,
    "reason": "A tenant credential is issued to a verified mailbox through POST /v1/provisioning/sandbox under a single-use identity assertion; it is never minted anonymously."
  },
  "steps": [
    {
      "step": 0,
      "id": "discover",
      "title": "Discover the machine surfaces",
      "requests": [
        "GET https://presence.decionis.com/llms-full.txt",
        "GET https://presence.decionis.com/.well-known/openapi.json",
        "GET https://presence.decionis.com/.well-known/mcp.json"
      ],
      "result": "The complete machine-readable reference, the OpenAPI 3.1 contract, and the MCP surfaces (the local @decionis/presence-mcp package and the Decionis hosted server that resolves a held ESCALATE with a Presence Check). No authentication."
    },
    {
      "step": 1,
      "id": "verify_offline",
      "title": "Verify a Presence Record with no account",
      "requests": [
        "GET https://presence.decionis.com/proof/example-presence-record — a sealed record: who, what, when, why, device, challenge, signature.",
        "GET https://presence.decionis.com/.well-known/presence-dossier-jwks.json — the active and retired Ed25519 verification keys.",
        "GET https://presence.decionis.com/verify-dossier.mjs (checksum: https://presence.decionis.com/verify-dossier.mjs.sha256) — the single-file verifier; run it with node against the record and the JWKS."
      ],
      "result": "The record's canonical bytes hash to its digest and its Ed25519 signature verifies against the published key, offline, without contacting Presence. The same check is available server-side as GET /v1/dossiers/{dossierId}/verify."
    },
    {
      "step": 2,
      "id": "operator",
      "title": "Hand the tenant step to your operator",
      "surface_to_operator": "Presence verifies people, so its tenant credential is issued to a verified mailbox. Open https://presence.decionis.com/start, confirm your email, and the sandbox workspace is provisioned in Shadow Mode; give me its presence_sk_ key on the server side and I will continue.",
      "requests": [
        "The operator's browser: https://presence.decionis.com/start (email confirmation → POST /v1/provisioning/sandbox under the single-use identity assertion; poll GET /v1/provisioning/sandbox/{runId})."
      ],
      "result": "A sandbox tenant with deterministic allow, block and escalate fixtures (POST /v1/sandbox/scenarios/{scenario}), permanently labelled sandbox_fixture — never production evidence. The tenant key is a server-side bearer secret; browsers and subjects only ever hold narrow session or invitation tokens."
    },
    {
      "step": 3,
      "id": "request",
      "title": "Hold an action until a named person approves it",
      "requests": [
        "POST https://presence.decionis.com/v1/verification-requests with header \"Authorization: Bearer <presence_sk_…>\" and an Idempotency-Key — the exact copy, values and verification requirements are sealed into an immutable envelope."
      ],
      "result": "request_id and an invitation credential for the approver's handoff (invitation_url, invitation_expires_at). The action stays held; nothing downstream executes. A replay with the same Idempotency-Key returns the same request."
    },
    {
      "step": 4,
      "id": "poll",
      "title": "Poll to a terminal status, then verify the record",
      "requests": [
        "GET https://presence.decionis.com/v1/verification-requests/{requestId} — until ALLOWED, BLOCKED or ESCALATED (each with a sealed receipt), or EXPIRED / CANCELLED.",
        "GET https://presence.decionis.com/v1/dossiers/{dossierId}/verify — re-verify the sealed Presence Record's signature and chain server-side.",
        "DELETE https://presence.decionis.com/v1/verification-requests/{requestId} — cancel a pending request; an autonomous BLOCK receipt is sealed so a cancelled action can never read as approved."
      ],
      "result": "A Presence Record whose approval carries the action's intent digest. It resolves this one action, once; it is evidence, never a transferable approval, and not an execution grant. Webhooks (verification.requested, decision.evaluated, escalation.opened) remove the need to poll tightly."
    },
    {
      "step": 5,
      "id": "mcp",
      "title": "Or run the Human Approval Gate as an MCP server",
      "requests": [
        "npx -y @decionis/presence-mcp with PRESENCE_API_KEY in the environment — tools presence_request_human_verification and presence_get_verification_status.",
        "Already on the Decionis hosted MCP server? decionis.request_presence_verification and decionis.get_presence_verification_status on https://protocol.decionis.com/mcp resolve a held Decionis ESCALATE with a Presence Check and re-evaluate; only the new Decionis verdict can return PROCEED."
      ],
      "result": "The same hold → approve → sealed-record loop inside the agent's tool calls. Fail-closed: expiry, cancellation and errors resolve to DENIED, and human approval alone is never execution authority."
    }
  ],
  "sandbox_tenant_cannot": [
    "Produce production evidence: every sandbox record carries evidence_class sandbox_fixture.",
    "Be provisioned without a verified mailbox: Presence verifies people, so its tenant credential is never minted anonymously.",
    "Enforce in production: production enforcement is sales-assisted, and the asynchronous authority loop (Authority Requests) is rollout-gated — disabled mode returns 503 and writes nothing.",
    "Turn human approval into execution authority: a Presence Record is evidence Decionis re-checks before commit, never a grant."
  ],
  "source_contracts": {
    "openapi": "https://presence.decionis.com/.well-known/openapi.json",
    "mcp": "https://presence.decionis.com/.well-known/mcp.json",
    "offline_verifier": "https://presence.decionis.com/verify-dossier.mjs",
    "verification_keys": "https://presence.decionis.com/.well-known/presence-dossier-jwks.json",
    "decision_authority": "https://decionis.com/.well-known/mcp.json"
  }
}