Создайте API-ключ в панели управления, выберите области доступа, обменяйте его на токен на 15 минут, храните надёжно и отзовите при необходимости.
API-ключ — это способ, которым ваши программы получают доступ к LinkHarbor API. Он принадлежит рабочему пространству, а не человеку, и может делать ровно то, что вы разрешили ему через области доступа (scopes). Для самих запросов вы обмениваете ключ на короткоживущий токен доступа.
Кто может создавать API-ключи?
- Владельцы и админы рабочего пространства — редакторы и наблюдатели видят в разделе «Callback и API» только карточку «Подключённые приложения»
- Начиная с Creator Pro; в Creator Free в карточке написано «API-ключи доступны начиная с Creator Pro.»
- Одновременно активны: до 5 ключей в Creator Pro, до 20 в Creator Agency, до 50 в Enterprise
Когда лимит достигнут, создание ключа завершается ошибкой 409 limit_reached. Сначала удалите ключ, который больше не нужен.
Создание API-ключа
- Откройте в навигации «Callback и API»
- В карточке «API-ключи» нажмите «+ Создать ключ»
- В поле «Название (необязательно)» введите название, по которому вы потом узнаете ключ, например «CI/CD Pipeline» или «Синхронизация магазина»
- В разделе «Области доступа» выберите для каждой области «Чтение» или «Запись»
- Нажмите «Создать ключ»
- Сразу скопируйте «Секрет ключа (приватный)» и сохраните его в надёжном месте
- Закройте диалог — ID ключа всегда можно найти в списке
- «Название (необязательно)»
- До 64 символов. Без названия ключ отображается в списке как «API-ключ #ID».
- «Области доступа»
- Нужна хотя бы одна. «Запись» автоматически включает «Чтение» для той же области. Статистика и платежи от поддержавших доступны только для чтения, шаблоны рабочего пространства — только для записи. Все области доступа описаны в статье Области доступа подробно.
- «Секрет ключа (приватный)»
- Начинается с lt_ и показывается ровно один раз («⚠️ Виден только один раз — скопируйте сейчас!»). LinkHarbor хранит только его хеш и не сможет показать его вам позже.
- «ID ключа:»
- 16 символов из цифр и заглавных букв A–F, например 6F668EA6598B0692. Он не секретный и отображается в списке с кнопкой копирования.
Список ключей
Для каждого активного ключа видны название, статус «Активен», ID ключа, его области доступа, «Создан:» и «Последнее использование:» или «Ещё не использовался». Время последнего использования обновляется при каждом запросе с этим ключом, но не чаще раза в минуту. «↺ Обновить» перезагружает список.
Обмен ключа на токен доступа
curl -X POST https://dock.at-harbor.com/v1/token \
-H "Content-Type: application/json" \
-d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }- token
- Токен доступа. Отправляйте его с каждым запросом как Authorization: Bearer <token>.
- expires_in
- Срок действия в секундах: 900, то есть 15 минут. Refresh-токена нет — когда срок истёк, просто получите новый токен с ID и секретом ключа.
Токен представляет рабочее пространство и несёт ровно области доступа ключа. Роли, как у человека, у него нет: эндпоинты, которые панель управления оставляет владельцам и админам (участники, оплата, управление доменами, вебхуки, настройки рабочего пространства), для токенов от API-ключей всегда закрыты. Исключения — короткие ссылки и шаблоны рабочего пространства, которые работают с соответствующей областью доступа, а также чтение секретов колбэков (без секрета в открытом виде) с read:workspaces.
Неудачные попытки и блокировка
| Ситуация | Ответ |
|---|---|
| Неверный ID ключа или секрет, или ключ удалён | 401 invalid_api_key |
| 5 неудачных попыток для одного ID ключа с одного IP | 429 api_key_locked, блокировка на 60 секунд |
| 10 неудачных попыток | 429 api_key_locked, блокировка на 5 минут |
| 20 неудачных попыток | 429 api_key_locked, блокировка на 30 минут |
| 50 неудачных попыток с одного IP за 10 минут | 429 rate_limited, IP блокируется на 1 час |
При api_key_locked оставшееся время указано в details.retry_after_sec. Успешный обмен сбрасывает счётчик.
Удаление и замена ключа
- Нажмите «Удалить» рядом с ключом
- Для подтверждения введите DELETE
- Нажмите «Удалить навсегда»
Ключ сразу перестаёт работать — уже выданные токены доступа тоже перестают действовать с этого момента и получают 401 invalid_token. Кнопки ротации нет. Чтобы сменить ключ, создайте новый, переведите на него свою программу, а затем удалите старый.
Если тариф понижается
Если рабочее пространство переходит на Creator Free, все API-ключи отзываются. Если оно переходит на тариф с меньшим числом ключей, самые новые сохраняются, а остальные отзываются. Отозванные ключи не возвращаются после последующего повышения тарифа — тогда вы создаёте новые. Владельцы получают письмо со списком отключённых функций. Подробнее — в статье Отмена и понижение тарифа.
Безопасность
- Храните секрет только в менеджере секретов или в переменных окружения, никогда в исходном коде или Git-репозитории
- Никогда не используйте его в коде, который выполняется в браузере или в приложении на устройстве пользователя
- Создавайте отдельный ключ для каждого приложения, с минимально возможным набором областей доступа
- Сразу удаляйте ключи, которые больше не нужны
- Если подозреваете утечку: удалите ключ и создайте новый
Вам также может пригодиться
Ничего не нашли?
Напишите, что вам нужно, и наша служба поддержки поможет вам лично.