Авторизация
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-время в миллисекундах.
Рекомендуемая стратегия обновления:
- Сохраните
access_tokenиexpires_atв памяти приложения. - Перед каждым запросом сверяйте: если до
expires_atосталось ≤ 30 секунд — обновите токен. - При ответе
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/секрет в нескольких разных сервисах. При
компрометации одного отзыв затронет всех, а журнал аудита не различит источник
запросов.