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 the canonical `agent_onboarding_url`. 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 `agent_enrollment_id` and poll `GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}`. Continue while the status is `pending`; when it becomes `claimed`, store the returned `agent_id`. Stop on `expired` or `revoked`. GET and list responses do not repeat the secret-bearing onboarding URL, so keep the create response secure until onboarding finishes. Tracking the exact Enrollment also 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 onboarding URL 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. ## Open the onboarding link Open the complete `agent_onboarding_url` unchanged, including its `#token` fragment. Do not parse, rebuild, proxy or log the URL. 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 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 status, Enrollment, Agent connectivity, printer discovery and Print API failures without requesting credentials. ## Next steps