Перейти к содержимому
Справочник API Получить API-ключи

Интеграция · Глава 4

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

Ваш бэкенд аутентифицируется секретным API-ключом; браузер или приложение пользователя получает только короткоживущий токен сессии.

3 мин чтения

API-ключи

Окружение Префикс Пример
Тестовый sk_test_ sk_test_i2fhPNWPG4cTmi1qCDVthAD7uTG6z6hf5lrHwddg
Боевой sk_live_ sk_live_sFeAQm0nrtHEOkc483XcnWDSvOpNK7CZ0ptBI0ij

Ключ — это префикс и 40 случайных букв и цифр. Окружение определяет ключ: тестовый ключ видит только тестовые данные, боевой — только боевые.

  • Создавайте ключи в панели: API-ключи → Создать ключ. Выберите окружение и дайте ключу имя (например, название сервиса, который его использует). Управлять ключами могут только владелец аккаунта и администраторы.
  • Полный ключ показывается один раз, сразу после создания. Мы храним только его хеш; позже панель показывает лишь первые символы, чтобы ключи можно было различать. Если ключ потерян, создайте новый.
  • Боевые ключи можно создать только после верификации бизнеса — см. Тестовый и боевой режимы.
  • Одновременно можно иметь несколько активных ключей, например по одному на сервис.
Важно

Никогда не размещайте секретный ключ в браузере, мобильном приложении, теме WordPress или публичном репозитории. Любой, у кого есть ключ, может создавать заявителей и читать данные документов в вашем аккаунте.

Передача ключа

Передавайте ключ в заголовке Authorization каждого запроса к https://kyc.goxost.net/api/v1:

curl https://kyc.goxost.net/api/v1/usage \
  -H "Authorization: Bearer $KYC_SECRET_KEY"
$kyc = new GuzzleHttp\Client([
    'base_uri' => 'https://kyc.goxost.net/api/v1/',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
]);
$usage = json_decode($kyc->get('usage')->getBody(), true);
const usage = await fetch('https://kyc.goxost.net/api/v1/usage', {
  headers: { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` },
}).then((r) => r.json());
usage = requests.get(
    "https://kyc.goxost.net/api/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"},
).json()
Проблема Ответ
Ключ отсутствует, неизвестен или отозван 401 unauthenticated
Аккаунт заблокирован или неактивен 403 forbidden
Боевой ключ, бизнес ещё не верифицирован 403 tenant_not_verified
ID принадлежит другому аккаунту или окружению 404 not_found

Единственный эндпоинт, которому не нужен ключ, — публичный каталог документов GET /documents/catalog.

Ротация и отзыв ключей

Чтобы сменить ключ без простоя:

  1. Создайте новый ключ в панели.
  2. Разверните его на своих серверах.
  3. Убедитесь, что старый ключ больше не используется, и нажмите Отозвать рядом с ним.

Отозванный ключ сразу перестаёт работать в API. Direct API ненадолго кеширует проверку ключа, поэтому там отозванный ключ может приниматься ещё до 60 секунд. Если ключ мог утечь, сразу отзовите его и создайте новый.

Токены сессий для браузера и приложения

Браузеру или мобильному приложению секретный ключ не нужен никогда. Когда ваш бэкенд создаёт сессию (POST /applicants/{id}/sessions), он получает два значения:

Значение Для чего
url Hosted-сценарий: перенаправьте пользователя, отправьте ссылку или покажите её QR-кодом
token SDK: передайте его в kyc.js или Flutter SDK

Оба относятся к одной сессии одного заявителя и истекают вместе с ней (60–1800 секунд, по умолчанию 30 минут). Ими нельзя вызвать /api/v1 и нельзя увидеть других заявителей. SDK сами отправляют токен сервису проверки как Authorization: Session <token> — вызывать эти эндпоинты напрямую не нужно.

Примечание

Результат, который SDK сообщает в браузере или приложении, нужен только для пользовательского опыта. Итоговое решение принимайте на бэкенде по вебхуку или GET /verifications/{id}.

Ключи идемпотентности

Сетевые ошибки случаются. Чтобы безопасно повторить запрос на запись, передавайте заголовок Idempotency-Key в запросах POST, PATCH и DELETE:

curl https://kyc.goxost.net/api/v1/applicants \
  -H "Authorization: Bearer $KYC_SECRET_KEY" \
  -H "Idempotency-Key: 3f1c9a7e-2b4d-4e8a-9c61-5d0f7b2a8e14" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user-8812"}'
  • Ключ — 8–64 символа из A–Z a–z 0–9 _ -. Хорошо подходит UUID. Неверный формат возвращает 400 bad_request.
  • В течение 24 часов тот же ключ с тем же запросом возвращает сохранённый ответ с заголовком Idempotent-Replayed: true. Ничего не создаётся дважды.
  • Тот же ключ с другим телом возвращает 409 idempotency_conflict.
  • Если первый запрос с этим ключом ещё выполняется, вы получите 409 conflict — подождите и повторите.
  • Ответы 5xx не сохраняются, поэтому повтор после ошибки сервера выполнит запрос заново.
  • Ключи действуют в пределах вашего API-ключа. Для каждой новой операции используйте новый ключ.

Лимиты запросов

Каждый API-ключ может отправлять 600 запросов в минуту. В каждом ответе есть X-RateLimit-Limit и X-RateLimit-Remaining. При превышении лимита вы получите 429 rate_limited с заголовком Retry-After (в секундах). У некоторых эндпоинтов есть дополнительные лимиты — см. Ошибки.