CloudPrint Documentation/API reference

Issue an App Installation token

Authenticate a Developer Application with a one-time RS256 assertion and issue a short-lived token for one approved App Installation.

POST/developer-api/v1/app-installations/{installationId}/access-tokensAPI version: v1operationId: issueInstallationAccessTokenView as Markdown

What this endpoint does

Authenticate a Developer Application with a one-time RS256 assertion and issue a short-lived token for one approved App Installation.

Authentication

Send a one-time RS256 Developer Application assertion in Authorization: Bearer <application_assertion>. This assertion is not a Public API access token.

Request

Production base URL: https://public-api.cloudprint.me/developer-api/v1/app-installations/{installationId}/access-tokens

Parameters

Name	Location	Type	Required	Description	Constraints
installationId	path	string (uuid)	yes	Stable UUID of the App Installation owned by the integrator mapping.	—
X-Request-Id	header	string	no	Optional request identifier for tracing; CloudPrint returns a safe value in the response header.	maxLength: 128; example: "order-100045-attempt-1"

Request body

Content type: application/json

Name	Type	Required	Description	Constraints
permissions	array	no	Permissions approved for the installation and included in this token.	—

Example requests

cURL

curl -sS https://public-api.cloudprint.me/developer-api/v1/app-installations/$INSTALLATION_ID/access-tokens \
  -H "Authorization: Bearer $APPLICATION_ASSERTION" \
  -H 'Content-Type: application/json' \
  -d '{"permissions":["documents:write","print_jobs:write"]}'

Response

HTTP status: 200 — Installation Access Token issued

Response fields

Name	Type	Required	Description	Constraints
access_token	string	yes	Short-lived OAuth2 Bearer token used in Public API requests.	example: "eyJ..."
token_type	string	yes	OAuth2 token type; Public API tokens use Bearer.	enum: Bearer
expires_in	integer	yes	Access-token lifetime in seconds from the time of issuance.	min: 1; example: 3600
installation_id	string (uuid)	yes	Stable UUID of the App Installation that authorized the token.	—
account_id	string (uuid)	yes	Stable UUID of the CloudPrint account that owns the resource.	—
permissions	array	yes	Permissions approved for the installation and included in this token.	—

Example response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "installation_id": "11111111-1111-4111-8111-111111111111",
  "account_id": "11111111-1111-4111-8111-111111111111",
  "permissions": [
    "agents:read"
  ]
}

Errors

HTTP status	Description
401	Application assertion is missing, invalid or already used
403	Developer Account customer access is not active
422	Installation is inactive or requested permissions are invalid
429	Rate limit exceeded
500	Unexpected error

Integration guidance

• Create a fresh assertion for this request: use RS256, the active key kid, the application client_id as both iss and sub, the exact endpoint URL as aud, a lifetime of at most five minutes and a unique jti.
• Store the stable installation_id against your own customer or tenant. This token endpoint accepts only installation_id; it does not accept your external customer identifier.
• There is no refresh token. Cache the installation token until shortly before expires_in, then issue another without asking the user to install again.

Related documentation

Installations and access tokensInstall an application into customer accounts, store installation_id and issue short-lived Installation Access Tokens.Get the current API client contextConfirm which CloudPrint account, client application and scopes are represented by the current access token.CloudPrint API errors and retriesHandle CloudPrint API status codes, machine-readable errors, rate limits, request tracing and safe retry decisions.

Service statusOpenAPIDeveloper PortalOpen accountPrivacy PolicyTermsDPAService Level Agreement