Authenticate with OAuth2 Client Credentials

Authentication is server-to-server OAuth2 Client Credentials. The client secret belongs only in a backend secret store; a browser, mobile app, local agent script or public repository must never receive it.

Create the client and scopes

Create one client app per external system and environment in the account UI. Standard printing requires printers:read, documents:write, print_jobs:write and print_jobs:read; add agents:read only when the integration reads /api/v1/agents. The secret is shown once.

Request and cache the token

bash

curl -sS https://public-api.cloudprint.me/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'scope=printers:read documents:write print_jobs:write print_jobs:read'

json

{
  "token_type": "Bearer",
  "expires_in": 900,
  "access_token": "eyJ..."
}

Cache the token until shortly before its 900-second lifetime expires. Do not request a token for every print.

Verify identity and scopes

bash

curl -sS https://public-api.cloudprint.me/api/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

json

{
  "account_id": "44444444-4444-4444-8444-444444444444",
  "account_name": "Acme Print Ops",
  "client_app_id": "33333333-3333-4333-8333-333333333333",
  "client_app_name": "Warehouse integration",
  "scopes": [
    "printers:read",
    "documents:write",
    "print_jobs:write",
    "print_jobs:read"
  ]
}

Use this setup check to prove which account and client app the token represents. It prevents a valid test token from silently routing work in the wrong customer account.

Handle OAuth and API failures

400 invalid_scope means the requested scope is unknown or not granted. 401 invalid_client at the token endpoint means the client credentials are wrong. A 401 from an API endpoint means the Bearer token is invalid or expired: refresh once and retry the original request once. 403 means the valid token lacks the required scope.

Rotate credentials

Issue a replacement client credential, deploy it through the secret manager and verify /api/v1/me before revoking the old client. Never print or log client_secret or the complete access token. X-Request-Id is safe to retain for request correlation.

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

CloudPrint Public API overviewA practical map of CloudPrint authentication, printers, documents, print jobs, statuses and errors for backend integrations.Connect an agent and select a printerInstall the CloudPrint agent, discover local printer queues and choose a stable printer ID based on its advertised capabilities.CloudPrint OpenAPI referenceExplore the complete CloudPrint Public API contract, request schemas, response models, authorization scopes and machine-readable JSON.

Authenticate with OAuth2 Client Credentials ​

Create the client and scopes ​

Request and cache the token ​

Verify identity and scopes ​

Handle OAuth and API failures ​

Rotate credentials ​

Production checklist ​

Next steps ​