인증 및 범위
모든 공개 API 요청은 장기간 사용 가능한 API 키를 bearer 토큰으로 전송해야 합니다. 범위는 각 키가 수행할 수 있는 작업을 제한합니다 — 통합에 실제로 필요한 것만 부여하세요.
Bearer 토큰 형식
API 키는 다음과 같이 표시됩니다:
scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH접두사 scs_live_는 키를 SecureCodingHub의 프로덕션 자격 증명으로 식별합니다. 토큰은 총 41자(9자 접두사 + 32자 무작위 본문)입니다. 키 생성 시 정확히 한 번만 반환됩니다.
모든 요청에서 표준 Bearer 인증 헤더로 토큰을 전송하세요:
Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDHAPI 키 생성
API 키는 API가 아니라 관리자 콘솔에서 생성됩니다.
조직 관리자로 app.securecodinghub.com에 로그인합니다.
사이드바에서 조직 → API 키을 엽니다.
+ 새 키 만들기을 클릭합니다. 키에 설명이 있는 이름을 지정합니다(예: GitHub Actions — CI 또는 Looker BI 동기화).
통합에 필요한 범위만 선택합니다. 읽기 전용 범위는 파란색으로, 쓰기 범위는 황색으로 강조 표시됩니다.
(선택 사항) 만료 날짜를 설정합니다. 만료 없이 생성된 키는 취소할 때까지 유효합니다.
키 만들기을 클릭합니다. 전체 토큰이 모달에 표시됩니다. 지금 시크릿 매니저에 복사하세요. 다시 검색할 수 없습니다 — 접두사와 마지막 4자만 저장됩니다.
범위 참조
SecureCodingHub는 읽기 및 쓰기 계층으로 나뉜 16개의 세분화된 범위를 사용합니다. 일치하는 범위 없이 엔드포인트에 도달한 요청은 응답 본문 {"error":"insufficient_scope","required":"…","present":[…]}와 함께 403 Forbidden을 반환합니다.
| 범위 | 리소스 | 계층 | 권한 |
|---|---|---|---|
org:read | 조직 | 읽기 | 조직 메타데이터 읽기(이름, 플랜, 좌석). |
users:read | 사용자 | 읽기 | 사용자 목록 조회; 사용자 상세 정보 조회. |
users:write | 사용자 | 쓰기 | 사용자 생성, 업데이트, 비활성화. |
teams:read | 팀 | 읽기 | 팀 및 구성원 목록 조회. |
teams:write | 팀 | 쓰기 | 팀 생성, 업데이트, 삭제. |
assignments:read | 과제 | 읽기 | 과제 목록 조회; 완료 상태와 함께 상세 정보 조회. |
assignments:write | 과제 | 쓰기 | 과제 생성, 업데이트, 비활성화. |
custom-courses:read | 맞춤 과정 | 읽기 | 항목과 함께 맞춤 과정 목록 조회. |
custom-courses:write | 맞춤 과정 | 쓰기 | 맞춤 과정 생성, 업데이트, 삭제. |
progress:read | 진행 상황 | 읽기 | 사용자별 연습 및 학습 진행 상황. |
certificates:read | 인증서 | 읽기 | 인증서 목록 조회 및 다운로드. |
audit-log:read | 감사 로그 | 읽기 | 감사 로그 항목 목록 조회. |
compliance:read | 컴플라이언스 | 읽기 | 컴플라이언스 대시보드 데이터. |
content:read | 콘텐츠 | 읽기 | 주제, 시나리오, CWE-주제 매핑. |
sarif:ingest | SARIF | 쓰기 | SARIF 실행을 수집하고 교육을 자동 할당합니다. |
webhook:manage | 웹훅 | 쓰기 | 아웃바운드 웹훅 엔드포인트를 관리합니다. |
권장 범위 세트
| 사용 사례 | 최소 범위 |
|---|---|
| CI/CD SARIF 수집 | sarif:ingest |
| HR 기반 사용자 프로비저닝 | users:write, teams:write |
| BI / 보고 내보내기 | users:read, progress:read, assignments:read, audit-log:read |
| 티켓팅 및 SOAR (이벤트 구독자) | webhook:manage, assignments:read |
| 감사관 읽기 전용 내보내기 | org:read, audit-log:read, compliance:read, certificates:read |
회전 및 취소
키를 회전하려면 먼저 교체를 생성하고, 새 토큰을 배포한 다음, 조직 → API 키에서 이전 키를 취소합니다. 취소는 즉시 적용됩니다 — 이전 토큰을 사용하는 진행 중인 요청은 몇 초 내에 401 Unauthorized을 반환하기 시작합니다.
키가 유출되면 취소하세요. "일시 중지" 상태는 없으며, 취소는 영구적입니다. 토큰은 다시 활성화할 수 없습니다.
저장소 모범 사례
- 토큰을 데이터베이스 비밀번호처럼 취급하세요. 절대 소스 컨트롤에 커밋하지 마세요.
- 플랫폼의 기본 시크릿 저장소(AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets, Vault, 1Password Connect)를 사용하세요.
- CI에서는 토큰이 필요한 단계에서만 주입하세요.
echo를 사용하지 마세요. - 통합별로 하나의 키를 발급하여 독립적으로 취소할 수 있도록 하세요. 단일 키를 CI, BI, SOAR 간에 공유하지 마세요.
- 단기간 통합(개념 증명, 공급업체 평가)을 위해 생성된 토큰에는 만료를 설정하세요.
일반적인 오류
| 상태 | 응답 | 의미 |
|---|---|---|
401 | {"error":"unauthorized"} | 누락, 잘못된 형식, 취소 또는 만료된 토큰입니다. |
403 | {"error":"insufficient_scope",…} | 토큰은 유효하지만 이 엔드포인트에 필요한 범위가 없습니다. |
429 | {"error":"rate_limited"} | 분당 또는 시간당 한도에 도달했습니다. 속도 제한을 참조하세요. |