Перейти к содержанию
Sursa для разработчиков

POST/v1/api-keys

Создать ключ API

create_api_key

Аутентификация

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры заголовков

  • Idempotency-Keystring

    Ключ для безопасного повтора записи: от 1 до 255 печатных символов ASCII; рекомендуется UUID v4 на каждую логическую операцию. Повтор с тем же ключом в течение 24 часов не выполняет операцию заново: он возвращает сохранённый ответ (статус, заголовки и тело) с заголовком Idempotency-Replayed: true. Тот же ключ с другим методом, путём, Content-Type или телом — ответ 409 api.idempotency_mismatch; пока первый запрос ещё выполняется — 409 api.idempotency_in_progress с Retry-After: 1. После ответа 5xx или 429 ключ освобождается, и повтор выполняет операцию заново. Ключ действует в пределах организации и вызывающей стороны (ключ API, пользователь или ключ своего источника).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Только для ключей API с ролью admin. Выполняет запрос от имени профиля доступа <profile>[:viewer|verifier|editor], например employee:viewer. Ключ установки этот заголовок использовать не может (403).

Параметры cookie

  • kb_view_asstring

    Cookie режима «Смотреть как» для сессии. POST /auth/view-as устанавливает её, DELETE /auth/view-as — сбрасывает.

Тело запроса

application/json

Объект: ApiKeyCreate

  • namestringобязательно

    length ≥ 1, length ≤ 64

  • rolestring

    По умолчанию: "editor"

  • data_profilestring | null

    Профиль доступа ключа. Без него ключ получает профиль организации по умолчанию. Профиль доступа не применяется к роли admin. Ключ администратора видит все данные организации, а профиль, отличный от full, возвращает 400 api_keys.data_profile_not_applicable.

  • expires_atstring (date-time) | null

    Время истечения ключа (ISO 8601, в будущем). null или отсутствие значения — ключ бессрочный.

  • scopesarray of ApiKeyScope | null

    Области доступа ключа. Если не заданы, они следуют за ролью: admin получает read, write, admin; editor и verifier — read, write; viewer — read. Область system выдаёт только администратор установки. Принимаются и тонкие области вида resource:action (ApiKeyScope); прежние read, write и admin раскрываются в наборы областей.

  • collection_idsarray of integer | null

    Ограничивает ключ этими коллекциями организации. Карточки, поиск, ответы и события работают только в них — поверх роли и профиля доступа. Нет значения или пустой список — без ограничения. Если вызывающий ключ сам ограничен коллекциями, новый ключ может быть только в его коллекциях. Без этого поля новый ключ получает коллекции вызывающего ключа. Пустой список или коллекция вне его списка возвращают 400 api_keys.invalid_collections.

    items ≤ 100

  • allowed_cidrsarray of string | null

    Сети, из которых можно использовать ключ, например 10.0.0.0/8 или 2001:db8::/32. Отдельный адрес — это сеть из одного адреса. Запрос с другого адреса возвращает 403 api_keys.ip_not_allowed. Нет значения — без ограничения.

    items ≤ 50

Ответы

200Успешный ответ

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

  • Idempotency-Replayed

    true — ответ воспроизведён из сохранённого для этого Idempotency-Key: операция повторно не выполнялась.

application/json

Объект: ApiKeyCreated

  • idintegerобязательно
  • namestringобязательно
  • prefixstringобязательно
  • roleRoleобязательно
  • created_atstring (date-time)обязательно
  • keystringобязательно
  • data_profilestring | nullобязательно
  • expires_atstring (date-time)

    Время истечения. Есть только у ключей со сроком действия.

  • scopesarray of string

    Явно заданные области доступа ключа. Есть только у ключей с явно заданными областями.

  • collection_idsarray of integer

    Ограничение по коллекциям. Есть только у ключей с ограничением.

  • allowed_cidrsarray of string

    Разрешённые сети. Есть только у ключей с ограничением.

400Запрос неверен: значение параметра или состояние объекта не позволяет выполнить действие (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

  • Retry-After

    Сколько секунд подождать перед повтором запроса.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Безопасные повторы

Передавайте заголовок Idempotency-Key (например, UUID) с каждым POST и PATCH. Повтор с тем же ключом в течение 24 часов возвращает сохранённый ответ, а не выполняет запрос снова.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← api-keys · Справочник API