Глоссарий
Ключ API
Ключ API это длинная случайная строка, которую программа шлёт вместо пароля, чтобы работать от лица аккаунта.
Зачем программе свой ключ
Пароль принадлежит человеку. С ним идут второй шаг входа, сессия с концом и устройство, которое надо иметь под рукой.
У сценария нет ничего из этого. Он идёт в три часа ночи на машине, куда никто не смотрит, и вопрос про код останавливает его насмерть.
Живёт до вашего отзыва
Ни ежедневного входа, ни набора руками. Ключ и есть весь пропуск целиком.
Прав у него меньше
Человек делает всё, что позволяет его роль. Ключ делает только то, что ему отметили.
Носит своё имя
Отдельный ключ на подрядчика или на сценарий это одна строка, закрываемая по окончании работы.
Права ключа
Права выбираются при выпуске и потом не расширяются. Ключ на чтение профилей не тронет прокси и не отметит браузер запущенным.
| Право | Что открывает |
|---|---|
| profiles:read | Список профилей. |
| profiles:write | Создание, правка и удаление профиля. |
| browser:run | Отметку профиля открытым и закрытым, без права его править. |
| proxies:read | Список сохранённых прокси, без паролей. |
| proxies:write | Создание, правку и удаление прокси. |
| flows:read | Список сохранённых сценариев. |
| logs:read | Вкладки «Действия», «Сессии профилей» и «Журнал IP». |
Список один и каждое право в нём что-то стережёт
Что говорит отказ вашему сценарию
На три разные беды приходят три разных ответа, и умение их различать это разница между починкой и часом догадок.
Ключ неизвестен
Отозванный ключ, набранный с ошибкой и никогда нам не принадлежавший читаются одинаково, и про аккаунт не подтверждается ничего.
401Тариф закончился
Ключ настоящий и права при нём целы. Не хватает только оплаты, и ответ говорит об этом прямо, а не намёком.
402Право не отмечено
Ключ годен, а ходу нужно право, которого у него нет. Выпустите новый ключ, а не ищите другой адрес.
403
Когда ключ перестаёт быть нужным
Ключ показывается один раз, в миг выпуска. Дальше хранится только его отпечаток и первые знаки, поэтому потерянный ключ заменяют, а не восстанавливают.
Что остаётся после отзыва
Отзыв действует со следующего вызова, а запись о ключе нарочно остаётся. Без неё в журнале стояли бы действия ключа, о котором уже никто ничего не скажет.
Закрытый доступ закрывает и ключи
Ключи всей команды видит владелец
Каждый человек в разделе «Ключи API» видит только свои ключи. Владелец и администратор команды ниже видят ещё раздел «Ключи API команды»: все ключи, выпущенные в этой команде, и ключи других людей тоже. У каждого ключа сказано, чей он, какие у него права, когда выдан, когда и с какого адреса им пользовались в последний раз.
Любой ключ команды отзывается кнопкой «Отозвать» в той же строке, после вопроса. Отозванный ключ перестаёт отвечать сразу, а в журнале остаётся запись «Ключ API отозван» с тем, кто отозвал, и почтой того, чей это был ключ. Сервер, обновлённый раньше этой версии, такого раздела не даёт.
Часто путают с этим
Токен доступа на своей машине
У локального API на вашем компьютере один токен доступа на всё, без прав и без срока. Он открывает окна браузера, чего серверный ключ не делает никогда.
Пропуск сессии
Человек входит и получает недолгий пропуск со всеми правами своей роли. Ключ уже по правам и живёт до отзыва.
Разовый код
Второй шаг входа доказывает, что человек за клавиатурой. Ключ существует ровно затем, чтобы там никого не было.
Чего это не делает
- Серверный ключ не открывает окон браузера. Запуск профиля из кода это дело локального API на вашем компьютере, а ключ лишь отмечает профиль занятым и пишет журнал.
- Ключом нельзя выпустить второй ключ или завести подписку на события. И то и другое требует входа паролем, поэтому утёкший ключ на чтение не расширит сам себя.
- Ход, у которого не объявлено право, ключу закрыт вовсе. Корзину и предпросмотр отпечатка читает человек, а не сценарий.
- Ключ это не отдельный участник команды. Он видит ровно то же, что и его хозяин, поэтому ограничение по группам у этого человека действует и на ключ.
- Ключ не ходит по командам хозяина. Он действует только в том пространстве, где выпущен, даже если хозяин состоит ещё в нескольких. Хозяин ушёл из этого пространства: ключ перестаёт работать, а отозвать его можно в своём пространстве.
Проверить
Каждое утверждение выше указывает на файл, который можно открыть, и на стенд, который идёт.
- Ключ хранится отпечатком и отдаётся один раз
- apps/server/src/api-keys/api-keys.service.ts · apps/server/test/api-keys.js
- Каждое право из списка стережёт настоящий ход, а ключи входят в платные тарифы
- apps/server/src/api-keys/scopes.ts · apps/server/test/права-ключей-живые.js · apps/server/test/ключи-платные.js
- Неизвестный ключ, кончившийся тариф и нехватка права это три разных ответа
- apps/server/src/auth/api-key.guard.ts
- Кабинет показывает секрет один раз и больше никогда
- apps/web/test/api-keys-web.js
- Ключ пространства, из которого хозяин ушёл, не действует и отзывается в своём
- apps/server/src/api-keys/api-keys.service.ts · apps/server/test/несколько-команд.js
Вопросы
- Сколько ключей можно держать сразу?
- Двадцать живых, и отозванные в этот счёт не идут. Предел стоит потому, что забытый ключ это дверь, про которую никто не помнит.
- Что будет, когда кончится подписка?
- Ключ перестанет работать, и в ответе причиной названа оплата. Тариф за ключом спрашивается по ходу работы, а не только в день выпуска.
- Можно ли запереть ключ на один профиль?
- Нет. Права выбираются по виду предмета, а не по самому предмету, поэтому самый узкий ключ это ключ, который только читает.
- Хранится ли сам ключ у вас?
- Нет. Хранится отпечаток для сверки и первые знаки, чтобы вы отличали свои ключи друг от друга. Их и показывает список.
- Как увидеть, что делал ключ?
- Журнал действий записывает ключ у каждой записи. Именно это и позволяет отозвать ключ одного подрядчика, не останавливая остальную автоматизацию.
Посмотрите права до выпуска ключа
Кабинет перечисляет все права ключа и называет, что открывает каждое, поэтому узкий ключ выпустить не сложнее широкого.