API-ключи

«Интабия Платформа» поддерживает API-ключи — способ дать внешней интеграции доступ к рабочему пространству, не заводя для неё обычную учётную запись человека. Ключ используется, например, для входящих вебхуков — внешние системы вызывают API Платформы от имени ключа, а не от имени сотрудника.

• У каждого ключа своя личность, и в истории видно именно её. Интеграционный ключ — это отдельная запись с именем ключа, не аккаунт того, кто его выпустил. Личный ключ действует от лица самого человека, но с отдельным идентификатором, поэтому написанное ключом отличимо от набранного руками.
• Интеграционный ключ не занимает место в тарифе — такие записи не учитываются лимитом мест (seats). Личный ключ места тоже не добавляет: он работает на месте своего владельца.
• Ключ отзывается отдельно и в любой момент, без последствий для чьего-либо личного членства в рабочем пространстве.

Ключи живут в Настройки → API + Webhooks. Их два вида:

• интеграционные — выпускает владелец рабочего пространства, ключ действует от имени собственной интеграционной записи. Квота: 5 активных на рабочее пространство;
• личные — выпускает себе любой участник, ключ действует с его собственными правами. Квота: 5 активных на человека.

При создании указываются:

• Имя — чтобы отличать ключи друг от друга в списке и в истории действий.
• Операции (только у интеграционного ключа) — какие действия на запись разрешено выполнять этим ключом (список — ниже). Чтение всегда разрешено и списком операций не ограничивается. Пустой список операций — это ключ только на чтение.
• Режим прав (только у личного ключа) — «полные права» (запись с правами самого человека) или «только чтение». Операции у личного ключа не выбираются, см. следующий раздел.
• Где действует — необязательный список проектов, каналов и папок: запись разрешена только в перечисленные. Пусто — всё рабочее пространство.
• Срок жизни токена — от 1 до 90 суток, по умолчанию 30. Определяет и срок самого ключа: дата истечения считается из этого числа и показывается рядом, отдельно её не выбирают.
• Входящие вебхуки — отдельный флаг: можно ли этим ключом стучаться в ingest-маршруты. Он не зависит от операций: ключ с полными правами без этого флага на ingest не пускается. С ним же у ключа появляется кнопка Правила — разбор чужого формата.

У интеграционного ключа вместо режима прав выбираются конкретные операции:

• Ключ с выбранными операциями пишет только через API операций — тот самый, куда ходят входящие вебхуки. Имя операции существует только там; в сырой транзакции его нет, сопоставить её с грантом не с чем, поэтому запись через обычный API такому ключу запрещена. Чтение — как обычно.
• Ключ с полными правами (личный, режим «полные права») пишет через любой API с правами своего пользователя; сузить его можно списком пространств.
• Ключ только на чтение не пишет нигде.

• issue:create — создание задачи
• issue:update — обновление задачи
• issue:comment — комментарий к задаче
• issue:time_report — списание времени на задачу и правка уже списанного
• chat:post — сообщение в канал
• doc:create — создание документа
• doc:update — обновление документа

Полное значение ключа показывается сразу после создания в отдельном окне и больше нигде не хранится и не отображается.

Дальше в списке ключей видны только префикс и последние 4 символа — этого достаточно, чтобы опознать нужный ключ, не имея возможности им воспользоваться.

Ключ выглядит так: fus_<рабочее-пространство>_<64 hex-символа>, например fus_myworkspace_7f3a9c...e21b. Префикс fus_ нужен, чтобы ключ узнавался как секрет Платформы — в том числе автоматическими сканерами утечек секретов и внутренними проверками логов.

Ротация ручная — автоматического обновления нет. Пока ключ не истёк, интеграция обменивает его на свежий токен столько раз, сколько нужно, точно так же, как в первый раз. Ключ и токен рассчитаны на один и тот же срок (1–90 суток, по умолчанию 30), поэтому к дате истечения нужно выпустить новый ключ и передать его интеграции.

Кнопка «Отозвать» в списке ключей — действие необратимое. Сразу после отзыва:

• Любой новый вызов с этим ключом — например, новый запрос к вебхук-эндпоинту — получает отказ: раскрытый ключ проверяется по базе на каждый запрос.
• Токен, уже выданный по этому ключу до отзыва, принудительно не отзывается — активная интеграция, использующая такой токен, продолжит работать, пока не истечёт сам токен (до 90 суток при максимальном сроке жизни). Если важно гарантированно и быстро оборвать доступ, держите срок жизни токена коротким.