Installations and access tokens
An App Installation is the stable relationship between one Developer Application and one customer CloudPrint Account. Store the installation, then issue short-lived account-scoped tokens whenever the backend needs the Print API.
Choose the installation model
Use this customer-authorized flow when the customer already owns a CloudPrint Account. For accounts provisioned by your product, use Partner Platform: it creates the App Installation through the Partner API without a customer consent redirect.
Start an installation
Build the CloudPrint installation URL with the Application client_id, one exact registered redirect_uri, an unpredictable state bound to the current user and tenant, and the permissions your product actually needs. Send the customer account owner to that URL. Do not accept an account ID supplied by your own frontend as proof of authorization.
Let the account owner approve access
CloudPrint shows the Application, Developer Account, public links and requested permissions before installation. The owner chooses the CloudPrint Account and explicitly approves access. Request the minimum permissions required for the product path; optional features can ask for additional permissions later through a visible approval flow.
Validate the callback
The callback contains installation_id, setup_action and the original state. Compare state using the server-side value, reject expired or reused attempts and bind the installation to the tenant that initiated the flow. Never use a CloudPrint Account ID as your integrator tenant identifier.
Issue an Installation Access Token
Create a fresh RS256 application assertion whose aud equals https://public-api.cloudprint.me/developer-api/v1/app-installations/{installationId}/access-tokens. Send it as Authorization: Bearer <application_assertion> to POST /developer-api/v1/app-installations/{installationId}/access-tokens. The response contains a short-lived access_token, expires_in, account_id, installation_id and effective permissions.
Use and cache the token
Send the Installation Access Token as a Bearer token to /api/v1/*. Cache it per installation until shortly before expiry instead of generating one token per print job. Concurrent workers should share or coordinate token refresh. There is no refresh token: issue another short-lived token from the unchanged installation.
Handle permissions and lifecycle
A requested token permission set must be a non-empty subset of the installation's effective permissions. A suspended installation cannot issue or use tokens until resumed; a revoked installation cannot be restored. On 401, invalidate the cached token and exchange once. On 403, inspect permissions or state instead of repeatedly refreshing.
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.