Перейти к содержанию

Авторизация

Pert API использует JWT-токены в заголовке Authorization. Сам токен выдаётся в обмен на запрос, подписанный вашим приватным ключом Ed25519. Сам ключ по сети не передаётся.

Порядок получения токена с примерами кода описан в разделе Начало работы. Здесь описаны состав подписываемых данных, проверка запроса, срок действия токена, его обновление и проверка.

Заголовки запросов

Заголовок Значение Когда нужен
Authorization Bearer <ACCESS_TOKEN> Защищённые методы; требования указаны в API-справочнике
X-Workspace-Id UUID рабочего пространства Методы, которые выбирают рабочее пространство по заголовку

Выбор рабочего пространства

Токен может предоставлять доступ к нескольким рабочим пространствам. В большинстве методов нужное пространство задаётся заголовком X-Workspace-Id; в некоторых — параметром пути, например tenant_uuid. Используйте способ, указанный в описании метода. При отсутствии доступа запрос завершится ошибкой 403.

Вызов из API-справочника

В API-справочнике откройте метод и нажмите «Проверить запрос». В разделе «Аутентификация» введите токен доступа без префикса Bearer. Заполните обязательные параметры, включая X-Workspace-Id, и нажмите «Отправить». Клиент покажет статус, заголовки и тело ответа.

Запрос выполняется на сервер из спецификации. Токен действует с вашими правами и сбрасывается при перезагрузке страницы. Для вызова из браузера сервер должен разрешать origin документации через CORS. Если браузер блокирует запрос, скопируйте пример cURL и выполните его локально.

Получение токена доступа

POST /api/v2/auth/access-token

Подписываемые данные

JSON-объект со следующими полями:

Поле Тип Обязательное Описание
client_type string да user — API-пользователь
client_id string да UUID API-пользователя
timestamp int64 да Unix-время в секундах (см. Серверное время)
nonce string да Новая случайная строка для каждого запроса. Рекомендуется не менее 16 случайных байт до кодирования

Сервер проверяет подписанные данные:

  • timestamp должен быть не старше 5 минут и не более чем на 1 минуту в будущем относительно серверного времени;
  • nonce обязателен и не должен быть пустым;
  • client_id должен соответствовать активному API-пользователю в указанной роли.

Тело запроса

Поле Тип Описание
data string Исходные байты JSON, закодированные в Base64
signature string Подпись Ed25519 исходных байтов JSON до кодирования, переданная в Base64

Что именно подписывается

Подпись считается над байтами JSON до base64-кодирования. Не подписывайте base64-строку и не меняйте сериализацию JSON (порядок полей, пробелы) после подписи — иначе сервер не сможет проверить подпись.

Ответ

{
  "access_token": "eyJhbGciOi...",
  "expires_at":   "1777300943056"
}
Поле Тип Описание
access_token string JWT, передавайте в заголовке Authorization: Bearer …
expires_at string Время окончания действия токена: Unix-время в миллисекундах, записанное строкой

Серверное время

GET /api/v2/auth/time

Метод не требует авторизации и возвращает текущее время сервера:

{
  "unix_seconds":      "1777300943",
  "unix_milliseconds": "1777300943056"
}

Когда использовать

Если часы вашей системы могут отличаться от серверных больше чем на минуту, запрашивайте время сервера перед подписанием запроса и используйте unix_seconds в поле timestamp. Это помогает избежать отказов из-за расхождения часов.

Срок действия и обновление токена

  • Срок жизни токена API-пользователя задаётся платформой; в текущей конфигурации — 20 минут.
  • Токен обновления (refresh token) не выдаётся: подпишите новый запрос и получите новый токен доступа.
  • Фактическое время окончания действия токена указано в expires_at — Unix-время в миллисекундах.

Рекомендуемая стратегия обновления:

  1. Сохраните access_token и expires_at в памяти приложения.
  2. Перед каждым запросом сверяйте: если до expires_at осталось ≤ 30 секунд — обновите токен.
  3. При ответе 401 Unauthorized с кодом TOKEN_EXPIRED или TOKEN_NEED_REFRESH получите новый токен и повторите запрос один раз.

Код TOKEN_REVOKED означает, что сессия завершена: получите новый токен. При общем коде UNAUTHORIZED проверьте сам токен или подпись запроса — причина может быть не связана со сроком действия.

Не запрашивайте новый токен на каждый вызов

Каждый вызов /api/v2/auth/access-token требует подписания и отдельного сетевого запроса. Сохраняйте токен в памяти приложения и используйте до обновления или окончания срока действия.

Что внутри токена

Токен доступа — это JWT с подписью EdDSA (Ed25519). Он содержит идентификатор владельца и массив data.accesses с правами доступа — по одному элементу на каждое рабочее пространство, в котором API-пользователю назначена роль:

Поле элемента accesses Описание
tenant_uuid UUID рабочего пространства
role Роль API-пользователя в этом рабочем пространстве (SIGNER, VIEWER, APPROVER, …)
permissions В JWT — битовая маска; в introspect — строковые имена разрешений
role_status Статус роли (ACTIVE в JWT; ROLE_STATUS_ACTIVE в introspect)

Доступ к нескольким рабочим пространствам

Если API-пользователю назначена роль в нескольких рабочих пространствах, один токен предоставляет доступ ко всем ним. Нужное пространство выбирается параметром, указанным в описании метода.

Проверка токена: introspect

POST /api/v2/auth/introspect

Возвращает сведения о текущем токене доступа: действителен ли он, когда выдан, до какого времени действует, кому принадлежит и какие права предоставляет. Используйте метод для проверки настроек интеграции и прав доступа.

curl -X POST https://auth.pert.paranoid.security/api/v2/auth/introspect \
    -H "Authorization: Bearer $ACCESS_TOKEN"

Ответ:

{
  "active":       true,
  "subject_type": "api_user",
  "subject_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "issued_at":    "1777299043056",
  "expires_at":   "1777300943056",
  "jti":          "f1b2…",
  "accesses": [
    {
      "tenant_uuid": "a1b2…",
      "role":           "SIGNER",
      "permissions":    ["VIEW_WORKSPACE", "SIGN_TRANSACTION", "INTROSPECT_TOKEN"],
      "role_status":    "ROLE_STATUS_ACTIVE"
    }
  ]
}

Ошибки

HTTP Причина Что делать
400 Некорректный формат данных, timestamp вне допустимого интервала, пустой nonce Сверьтесь с серверным временем, проверьте формат JSON
401 Неверная подпись, отсутствует Authorization (UNAUTHORIZED); истёкший или устаревший токен (TOKEN_EXPIRED, TOKEN_NEED_REFRESH); отозванный токен (TOKEN_REVOKED) Получите новый токен или заново подпишите запрос в зависимости от кода ошибки. Подписывайте исходные байты JSON до кодирования в Base64
403 Нет доступа к выбранному рабочему пространству или у роли нет нужного разрешения Проверьте accesses через introspect; запросите нужные права у владельца рабочего пространства
401 API-пользователь не найден, неактивен или подпись неверна Проверьте client_id, ключ и состояние пользователя

Безопасность приватного ключа

  • Хранилище: secrets-менеджер (Vault, AWS/GCP/Azure Secrets Manager, KMS), не репозиторий и не env-файл в образе.
  • Доступ: только тот процесс, который реально подписывает запросы. Никаких chmod 644.
  • Ротация: создайте нового API-пользователя с новой парой ключей, переключите интеграцию, затем деактивируйте старого. Не используйте один client_id с двумя ключами.
  • Компрометация: немедленно деактивируйте API-пользователя в консоли. После применения блокировки или удаления ранее выданные токены отзываются или требуют обновления. Удаление из одного рабочего пространства отзывает доступ к нему; права в других пространствах могут сохраниться. При включённом согласовании изменение сначала должно быть одобрено.

Один API-пользователь — одна интеграция

Не используйте один client_id/секрет в нескольких разных сервисах. При компрометации одного отзыв затронет всех, а журнал аудита не различит источник запросов.