Ключи API
Ключ API аутентифицирует программный доступ к публичному API DataForge. Каждый запрос к публичному API идентифицируется ключом, и ключ действует от имени того пользователя, которому он принадлежит. Ключи создаются и управляются в карточке пользователя в списке пользователей: Настройки → Пользователи или Настройки → Моя компания для пользователей своей компании.
Общая информация
| Свойство | Значение |
|---|---|
| Заголовок запроса | X-Api-Key: <ключ> |
| Количество ключей на пользователя | Не более одного активного ключа |
| Срок действия | Ключ не имеет срока действия: он работает, пока не будет заменён новым ключом или удалён |
| Хранение | Хранится только хэш ключа, само значение ключа никогда не возвращается в ответах API |
| Кто может создавать и удалять ключи | Суперадминистратор, Администратор компании |
| Транспорт | HTTPS с TLS 1.2 или выше |
Примечания:
- Значение ключа отображается только в момент его создания. Скопируйте ключ и сохраните его в надёжном месте — прочитать его в приложении позже нельзя
- Ключ предоставляет доступ к учётной записи без пароля, поэтому обращаться с ним нужно как с учётными данными
- Удалённый или заменённый новым ключ перестаёт работать сразу
Создание ключа
- Откройте Настройки → Пользователи (или список пользователей своей компании) и откройте карточку пользователя на редактирование
- В поле API-ключ нажмите Создать API-ключ. Для пользователя, у которого ключ уже есть, кнопка называется Создать новый ключ
- Подтвердите операцию в диалоговом окне. Создание нового ключа делает предыдущий недействительным: все системы и приложения, использующие старый ключ, потеряют доступ к API и перестанут работать, пока ключ не будет обновлён в их настройках
- Скопируйте созданное значение по значку копирования в поле API-ключ
- Нажмите Сохранить. До сохранения формы новый ключ не применяется
Уже сохранённый ключ отображается в поле API-ключ скрытым, прочитать его из поля нельзя.
Удаление ключа
- Откройте карточку пользователя на редактирование
- Нажмите Удалить API-ключ и подтвердите операцию
- Нажмите Сохранить
После удаления все системы и приложения, использовавшие ключ, теряют доступ к API. Пользователю в любой момент можно выдать новый ключ.
Использование ключа
Ключ передаётся в заголовке X-Api-Key каждого запроса к публичному API — как в версии v1, так и в версии v2:
GET /df-api/v2/projects
X-Api-Key: <ключ>
Запросы без заголовка или со значением, не соответствующим ни одному сохранённому ключу, отклоняются с кодом 401. Базовые URL для локальной и облачной инсталляций приведены на главной странице раздела.
К чему даёт доступ ключ
У ключа нет собственных прав — он разрешается в учётную запись, для которой был создан, и в доступ этой учётной записи к проектам:
| Правило | Поведение |
|---|---|
| Статус учётной записи | Учётная запись должна быть активна. Заблокированная или отключённая учётная запись не может использоваться даже с корректным ключом |
| Область по проектам | Ключ наследует доступ к проектам своего владельца. Эндпоинты, адресованные конкретному проекту, возвращают 404 Not Found, если у владельца нет доступа к этому проекту — факт существования проекта не раскрывается |
| Списки проектов | GET /projects возвращает только проекты, доступные владельцу ключа; остальные исключаются из страницы и из общего количества |
| Чтение и запись | Эндпоинты v1 доступны только на чтение. Эндпоинты v2 позволяют также создавать, изменять и удалять данные |
| Права на запись | Запись в РПИ и модель данных требует, чтобы эффективная роль владельца в проекте была «разработчик» или выше; более низкий уровень отклоняется с кодом 403 |
| Управление доступом | Эндпоинты v2 для управления доступом и владением дополнительно требуют, чтобы владелец ключа был владельцем проекта, Администратором компании или Суперадминистратором |
| Лицензия | Весь публичный API доступен только при действующей лицензии компании |
| Фильтрация по IP | Белый и чёрный списки IP компании применяются к запросам с ключом так же, как при обычном входе в систему |
Ограничение частоты запросов
| Поверхность | Ограничение |
|---|---|
/df-api/v1 |
Ограничение не применяется |
/df-api/v2 |
100 запросов за 60 секунд на один ключ |
Каждый ответ /df-api/v2 содержит текущее состояние счётчика в заголовках X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. При превышении ограничения запрос отклоняется с кодом 429 Too Many Requests и кодом ошибки RATE_LIMIT_EXCEEDED.
Ошибки аутентификации
| Код | HTTP | Когда возвращается |
|---|---|---|
API_KEY.KEY_MISSING |
401 | Заголовок X-Api-Key не передан |
API_KEY.INVALID_KEY |
401 | Ключ не соответствует ни одному сохранённому — например, он был удалён или заменён новым |
API_KEY.AUTH_FAILED |
401 | Общий сбой аутентификации |
API_KEY.INVALID_ENCRYPTED_API_KEY |
400 | Переданный ключ не удалось декодировать |
API_KEY.ACCOUNT_LOCKED |
403 | Учётная запись владельца ключа не активна |
API_KEY.IP_BLOCKED |
403 | IP клиента находится в чёрном списке компании или вне её белого списка |
API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE |
403 | У компании нет действующей лицензии |
RATE_LIMIT_EXCEEDED |
429 | Превышено ограничение частоты запросов на ключ (/df-api/v2) |
Журналирование
Каждый запрос к публичному API записывается в системный журнал в категории доступа к API вместе с его результатом:
- Успешный запрос записывается как успешное обращение к API
- Отклонённый или завершившийся ошибкой запрос записывается как неуспешное обращение к API, а причина (отсутствующий или некорректный ключ, заблокированная учётная запись, заблокированный IP, недействительная лицензия, превышение ограничения частоты запросов) добавляется в запись
- Каждая успешная операция записи через API v2 дополнительно сохраняет снимок затронутого объекта до и после изменения
Каждая запись содержит email владельца ключа, IP-адрес клиента, компанию, название и версию API и эндпоинт. Системный журнал доступен в разделе Настройки → Системный журнал ролям Администратор компании и Суперадминистратор.