Enroll an agent for a customer
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.