인증

Open API v2는 OAuth2 client_credentials 그랜트를 사용합니다. 장수명 정적 API 키는 없습니다 — 대시보드에서 발급한 크리덴셜로 15분짜리 ES256 액세스 토큰을 받아 Authorization: Bearer로 호출합니다. 유출 창을 최소화하기 위한 설계입니다.

흐름 한눈에

1. 대시보드 Developers 메뉴에서 API 클라이언트를 발급 → client_id + client_secret.
2. POST https://auth.kolleges.net/token으로 15분 토큰 교환(서버측·매 만료마다).
3. 토큰을 Authorization: Bearer로 https://openapi.kolleges.net/v2/… 호출.

클라이언트 인증 (client_secret)

client_id + client_secret을 HTTP Basic으로 제시합니다.

curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=client_credentials' \
  -d 'scope=kolleges:openapi:issuance:write' \
  https://auth.kolleges.net/token

secret은 해시만 보관됩니다

client_secret은 발급 화면에서 한 번만 노출됩니다. 플랫폼은 해시만 저장하며 재열람이 불가합니다. 분실 시 회전(rotate)하세요 — 회전은 새 secret을 발급하고 이전 secret을 무효화합니다.

토큰 속성

속성	값
알고리즘	ES256 (JWT)
수명	900초 (15분)
audience (aud)	https://openapi.kolleges.net
issuer (iss)	https://auth.kolleges.net
scope	요청 scope ∩ 클라이언트 등록 scope

audience 격리

Open API v2 토큰의 aud는 다른 Kolleges API 표면과 완전히 분리됩니다. openapi 토큰으로 다른 표면을 호출할 수 없고, 그 역도 불가합니다 — 크리덴셜이 레인을 넘지 못합니다.

Scope (최소 권한)

scope는 kolleges:openapi:<operation> 네임스페이스입니다. deny-by-default — 클라이언트에 등록된 scope만 요청할 수 있고, 토큰에는 요청 ∩ 등록의 교집합만 실립니다.

scope를 생략하지 마세요

scope 파라미터를 생략하면 요청 집합이 비어 scope 없는 토큰이 발급됩니다(등록 allowed를 자동 위임하지 않습니다). 그 토큰의 모든 /v2 호출은 403이 됩니다. 필요한 operation만 명시적으로 요청하세요.

scope	용도
kolleges:openapi:clubs:read	클럽 신원·발급 가능 여부
kolleges:openapi:issuance:read	발급 목록·상세·파일
kolleges:openapi:issuance:write	발급
kolleges:openapi:issuance:revoke	취소(무효화)
kolleges:openapi:achievements:read / :manage	achievement 조회 / 저작
kolleges:openapi:designs:read / :manage	디자인 조회 / 저작
kolleges:openapi:billing:read	요금·엔타이틀먼트
kolleges:openapi:events:read	이벤트 피드

키 회전

client_secret이 유출되었거나 주기적 교체가 필요하면 대시보드에서 회전합니다. 회전 직후에는 신·구 secret이 잠시 함께 유효하여(무중단 교체) 배포 중 토큰 발급이 끊기지 않습니다. 교체가 끝나면 이전 secret은 무효화됩니다.