Set up an Agent for a managed account
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.