Аутентификация и области доступа
Каждый запрос к публичному API должен нести долгоживущий API-ключ как bearer-токен. Области ограничивают, что каждому ключу разрешено делать — предоставляйте только то, что Вашей интеграции действительно нужно.
Формат Bearer-токена
API-ключи выглядят так:
scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHПрефикс scs_live_ идентифицирует ключ как продакшен-учётные данные для SecureCodingHub. Токены имеют 41 символ всего (9-символьный префикс + 32-символьное случайное тело). Они возвращаются ровно один раз при создании ключа.
Отправляйте токен на каждом запросе как стандартный заголовок Bearer-аутентификации:
Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHСоздание API-ключа
API-ключи создаются в админ-консоли — не через API.
Войдите в app.securecodinghub.com как администратор организации.
Откройте Организация → API-ключи из боковой панели.
Нажмите + Создать новый ключ. Дайте ключу описательное имя (например, GitHub Actions — CI или Looker BI sync).
Отметьте только области, нужные интеграции. Области только для чтения подсвечены синим, write-области — янтарным.
(Опционально) Установите дату истечения. Ключи без истечения остаются действительными, пока Вы их не отзовёте.
Нажмите Создать ключ. Полный токен показывается в модальном окне. Скопируйте его в Ваш менеджер секретов сейчас. Вы не сможете получить его снова — только префикс и последние четыре символа хранятся.
Справочник областей
SecureCodingHub использует 16 точных областей, разделённых на read- и write-уровни. Запрос, попадающий на эндпоинт без соответствующей области, возвращает 403 Forbidden с телом ответа {"error":"insufficient_scope","required":"…","present":[…]}.
| Область | Ресурс | Уровень | Предоставляет |
|---|---|---|---|
org:read | Организация | Read | Чтение метаданных организации (имя, план, места). |
users:read | Пользователи | Read | Список пользователей; получение деталей пользователя. |
users:write | Пользователи | Write | Создание, обновление, деактивация пользователей. |
teams:read | Команды | Read | Список команд и участников. |
teams:write | Команды | Write | Создание, обновление, удаление команд. |
assignments:read | Задания | Read | Список заданий; получение деталей с завершением. |
assignments:write | Задания | Write | Создание, обновление, деактивация заданий. |
custom-courses:read | Пользовательские курсы | Read | Список пользовательских курсов с элементами. |
custom-courses:write | Пользовательские курсы | Write | Создание, обновление, удаление пользовательских курсов. |
progress:read | Прогресс | Read | Прогресс практики и обучения на пользователя. |
certificates:read | Сертификаты | Read | Список и скачивание сертификатов. |
audit-log:read | Журнал аудита | Read | Список записей журнала аудита. |
compliance:read | Соответствие | Read | Данные панели соответствия. |
content:read | Контент | Read | Темы, сценарии, сопоставление CWE-тема. |
sarif:ingest | SARIF | Write | Приём SARIF-ранов и автоназначение обучения. |
webhook:manage | Webhook'и | Write | Управление исходящими webhook-эндпоинтами. |
Рекомендуемые наборы областей
| Случай использования | Минимальные области |
|---|---|
| Приём SARIF из CI/CD | sarif:ingest |
| Провижининг пользователей через HR | users:write, teams:write |
| BI / экспорт отчётов | users:read, progress:read, assignments:read, audit-log:read |
| Тикетинг и SOAR (подписчики событий) | webhook:manage, assignments:read |
| Read-only экспорт аудитора | org:read, audit-log:read, compliance:read, certificates:read |
Ротация и отзыв
Чтобы ротировать ключ, создайте замену сначала, разверните новый токен, затем отзовите старый в Организация → API-ключи. Отзыв вступает в силу немедленно — запросы в полёте, использующие старый токен, начнут возвращать 401 Unauthorized в течение секунд.
Если ключ утёк, отзовите его. Нет состояния «pause»; отзыв постоянный. Токен нельзя повторно включить.
Лучшие практики хранения
- Относитесь к токену как к паролю базы данных. Никогда не коммитьте его в систему контроля версий.
- Предпочитайте нативное хранилище секретов Вашей платформы (AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets, Vault, 1Password Connect).
- В CI внедряйте токен только на том шаге, которому он нужен; избегайте его
echo. - Выпускайте один ключ на интеграцию, чтобы Вы могли отзывать независимо. Не делите один ключ между CI, BI и SOAR.
- Устанавливайте срок истечения на токены, созданные для краткосрочных интеграций (proofs of concept, оценки вендоров).
Распространённые ошибки
| Статус | Ответ | Значение |
|---|---|---|
401 | {"error":"unauthorized"} | Отсутствующий, неправильно сформированный, отозванный или истёкший токен. |
403 | {"error":"insufficient_scope",…} | Токен валиден, но не имеет требуемой области для этого эндпоинта. |
429 | {"error":"rate_limited"} | Лимит в минуту или в час достигнут. См. Лимиты запросов. |