Agent Enrollment connects one or more local CloudPrint Agents to the intended managed customer account without requiring the customer to register or sign in to CloudPrint.
## Create every Enrollment idempotently Initial provisioning returns one hosted `agent_onboarding_url` carrying a single-use token. Add another computer before or after onboarding with `POST /partner-api/v1/accounts/{relationshipId}/agent-enrollments` and a mandatory `Idempotency-Key`. An exact replay returns the original Enrollment ID, expiry and URL. Persist the pending key, `state`, name, callback and optional `replaces_enrollment_id` before the first request; only the application assertion changes on retry. Use `replaces_enrollment_id` when replacing a known unused Enrollment. ## Track the exact Enrollment Persist the returned `enrollment_id` and poll `GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}`. Continue while it is `pending`; on `ready`, store the returned `agent_id`. Stop on `expired`, `cancelled` or `failed`. This avoids mistaking an Agent that was already connected for the computer using the new link. ## List and revoke Enrollment records Use `GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments` to inspect pending, claimed, expired and revoked records; listing never exposes secret codes. Revoke one unused code with `DELETE /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}`. Repeating a revoke is safe. ## List and revoke connected Agents Use `GET /partner-api/v1/accounts/{relationshipId}/agents` to show every connected computer and its state. Replace a lost, broken or retired computer by revoking it through `DELETE /partner-api/v1/accounts/{relationshipId}/agents/{agentId}` and creating a new Enrollment. Revocation takes that Agent's printers offline. ## Recover a lost Enrollment response Retry the exact Enrollment request with a fresh single-use assertion and the same Enrollment `Idempotency-Key`. CloudPrint returns the original secret while the idempotency record is retained. A different body or route with the same key returns `409 partner.idempotency.conflict`; do not invent a new key after an uncertain response. ## Use hosted onboarding without configuring Agent API Open the complete `agent_onboarding_url` unchanged, including its `#token` fragment; do not parse, rebuild, proxy or log it. CloudPrint owns Agent API routing and fallback. Public installers are discovered through `GET /agent-download-api/v1/releases` and downloaded by the returned filename through `GET /agent-download-api/v1/installers/{filename}`. After the callback, verify `state`. `result=ready` confirms the first authenticated Agent heartbeat, not printer availability. Refresh the managed Account, Agents and the printer list; enable printing only when `status=active`, `online_agent_count > 0` and `online_printer_count > 0`. ## Give support actionable context Store the customer ID, `relationship_id`, `installation_id`, Enrollment ID, Agent ID, Agent version, last-seen state and relevant `X-Request-Id` values. Support should distinguish account lifecycle, Enrollment, Agent connectivity, printer discovery and Print API failures without requesting credentials. ## Production checklist - Use an outbound agent connection; do not expose printer ports to the internet. - Store the stable printer identity instead of relying only on a display name. - Validate document format, page size and orientation before creating the job. - Handle terminal status, retry policy and duplicate-print protection explicitly. ## Next steps