CloudPrint Documentation/Build with API

OAuth integration for third-party applications

Use a developer application when your product must let many independent CloudPrint customers connect their own accounts. CloudPrint creates the developer organization and OAuth application on request; each customer then grants access explicitly through Authorization Code with PKCE.

Choose the correct integration model

Use API Credentials when one customer connects a backend they control to their own CloudPrint account. Request a Developer Organization when you publish a product, connector or marketplace integration used by other CloudPrint customers. A developer application cannot use client_credentials; every customer connection starts with consent.

Request a developer account

Contact CloudPrint through the integration contact section. Include your organization and product name, technical contact, use case, homepage, privacy-policy URL, exact HTTPS callback URI and the minimum scopes you need. CloudPrint creates the OAuth application and delivers its client_id and one-time client_secret securely. Self-service creation is not currently available.

Register the application URLs

Provide a public HTTPS homepage, privacy-policy URL and callback URI. Redirect URIs are exact matches: scheme, host, port, path and trailing slash must be the same in the authorization request, token exchange and registered application. Register every callback path your product actually uses and reject redirects to any other location.

Start Authorization Code with PKCE

Generate a cryptographically random, single-use state and PKCE code_verifier; store them in a short-lived server-side login transaction. Derive the S256 challenge and redirect the user's browser:

https://my.cloudprint.me/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fintegrations%2Fcloudprint%2Fcallback&
  scope=printers%3Aread%20documents%3Awrite%20print_jobs%3Awrite&
  state=RANDOM_SINGLE_USE_VALUE&
  code_challenge=BASE64URL_SHA256_OF_VERIFIER&
  code_challenge_method=S256

Do not put client_secret in this browser URL. The signed-in CloudPrint user reviews the application, organization and requested scopes before approving.

Validate the callback and exchange the code

On the callback, reject a missing, expired or mismatched state. Exchange the short-lived code from your backend with the original verifier:

curl -sS https://public-api.cloudprint.me/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=https://app.example.com/integrations/cloudprint/callback' \
  --data-urlencode 'code=CODE_FROM_CALLBACK' \
  --data-urlencode 'code_verifier=ORIGINAL_PKCE_VERIFIER'

The callback URI must be byte-for-byte identical to the registered value. Store tokens against the customer organization that initiated the connection, never as one global product token.

Refresh and revoke safely

Access tokens are short-lived; refresh them from your backend before expiry:

curl -sS https://public-api.cloudprint.me/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'refresh_token=STORED_REFRESH_TOKEN'

Encrypt the client secret and refresh tokens at rest, prevent concurrent refresh races and never log complete tokens. A customer can revoke the connection in Integrations → Authorized Apps; treat a failed refresh or API 401 as disconnected and ask the customer to authorize again.

Finish the customer connection

After the first token exchange, call /api/v1/me and verify the returned account and scopes. Then list printers, let the customer assign stable printer_id values to locations or workflows, and save CloudPrint IDs with your own organization IDs. Use the normal document and print-job APIs after that setup.

Launch checklist

Before connecting customers, verify callback and refresh handling end to end, use minimal scopes, publish a real privacy policy, document disconnect behavior, verify idempotent printing and provide a support contact. Never silently fall back to another customer's printer when a grant is revoked.

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

Authenticate with OAuth2 Client CredentialsCreate a CloudPrint client app, request a short-lived access token and protect credentials with the correct API scopes.CloudPrint Public API overviewA practical map of CloudPrint authentication, printers, documents, print jobs, statuses and errors for backend integrations.CloudPrint OpenAPI referenceExplore the complete CloudPrint Public API contract, request schemas, response models, authorization scopes and machine-readable JSON.

OpenAPIOpen accountPrivacy PolicyTermsPayment and refundsDPA