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.
Ротация и отзыв ключей
Чтобы сменить ключ без простоя:
- Создайте новый ключ в панели.
- Разверните его на своих серверах.
- Убедитесь, что старый ключ больше не используется, и нажмите Отозвать рядом с ним.
Отозванный ключ сразу перестаёт работать в 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 (в секундах). У некоторых эндпоинтов есть дополнительные лимиты — см. Ошибки.