Документация CloudPrint/Справочник API

Получить токен установки приложения

Подтвердите Developer Application одноразовым JWT, подписанным RS256, и получите короткоживущий токен для одной App Installation.

POST/developer-api/v1/app-installations/{installationId}/access-tokensВерсия API: v1operationId: issueInstallationAccessTokenОткрыть в Markdown

Назначение метода

Подтвердите Developer Application одноразовым JWT, подписанным RS256, и получите короткоживущий токен для одной App Installation.

Авторизация

Передавайте одноразовое JWT-подтверждение Developer Application, подписанное RS256, в Authorization: Bearer <application_assertion>. Это не токен доступа к Public API.

Запрос

Основной адрес API: https://public-api.cloudprint.me/developer-api/v1/app-installations/{installationId}/access-tokens

Параметры

Имя	Расположение	Тип	Обязательно	Описание	Ограничения
installationId	path	string (uuid)	да	Стабильный UUID App Installation, который интегратор хранит в своём сопоставлении.	—
X-Request-Id	header	string	нет	Необязательный идентификатор для трассировки запроса; CloudPrint вернёт безопасное значение в заголовке ответа.	maxLength: 128; example: "order-100045-attempt-1"

Тело запроса

Тип содержимого: application/json

Имя	Тип	Обязательно	Описание	Ограничения
permissions	array	нет	Разрешения установки, включённые в этот токен.	—

Примеры запросов

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"]}'

Ответ

HTTP-статус: 200 — Запрос выполнен.

Поля ответа

Имя	Тип	Обязательно	Описание	Ограничения
access_token	string	да	Короткоживущий OAuth2 Bearer-токен для запросов к Public API.	example: "eyJ..."
token_type	string	да	Тип OAuth2-токена; Public API использует Bearer.	enum: Bearer
expires_in	integer	да	Срок действия токена доступа в секундах с момента выдачи.	min: 1; example: 3600
installation_id	string (uuid)	да	Стабильный UUID App Installation, выдавшей разрешение токену.	—
account_id	string (uuid)	да	Стабильный UUID аккаунта CloudPrint, которому принадлежит ресурс.	—
permissions	array	да	Разрешения установки, включённые в этот токен.	—

Пример ответа

{
  "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"
  ]
}

Ошибки

HTTP-статус	Описание
401	Авторизация отсутствует или недействительна.
403	Для операции недостаточно разрешений.
422	Поля запроса не прошли проверку.
429	Превышен лимит запросов; учитывайте Retry-After.
500	Внутренняя ошибка CloudPrint.

Рекомендации по интеграции

• Для каждого запроса создавайте новое одноразовое JWT-подтверждение: используйте RS256, kid активного ключа, client_id приложения в iss и sub, точный URL метода в aud, срок не более пяти минут и уникальный jti.
• Свяжите постоянный installation_id с идентификатором клиента в своей системе. Метод принимает только installation_id, а не ваш внешний идентификатор клиента.
• Refresh token не выдаётся. Кешируйте токен установки почти до окончания expires_in, затем выпускайте новый без повторной установки приложения пользователем.

Связанная документация

Установки и токены доступаУстанавливайте приложение в аккаунты клиентов, сохраняйте installation_id и выпускайте короткоживущие Installation Access Tokens.Получить контекст API-клиентаПроверьте, к какому аккаунту и API-приложению относится текущий токен и какие разрешения ему выданы.Ошибки и повторы CloudPrint APIОбрабатывайте HTTP-статусы, машиночитаемые ошибки, ограничения частоты запросов, трассировку и безопасные повторы.

Статус сервисаOpenAPIКабинет разработчикаОткрыть кабинетПолитика конфиденциальностиУсловия использованияDPAСоглашение об уровне сервиса