콘텐츠로 이동
Kolleges Developers

Quickstart

kolleges를 API로 자동화하려는 직접 고객(자기 클럽의 데이터컨트롤러)을 위한 시작 가이드입니다. 정본 계약 = Open API v2 레퍼런스. 여러 클럽을 대행 운영하는 채널 파트너라면 별도의 Partner API 레퍼런스(호스트 partner.kolleges.net)를 참조하세요. 발급된 크리덴셜을 검증·되읽기만 하는 쪽(검증자·지갑·LMS)은 인증이 필요 없는 Open Badges 3.0 공개 검증 레퍼런스(호스트 api.kolleges.net)를 보세요 — 서명된 VC-JWT 가 유일한 동결 기록이고, 취득조건·스킬·각인 설명은 그 안에서 읽습니다.

한 장 개념

섹션 제목: “한 장 개념”
  • API 클라이언트(apiClient) = 대시보드에서 발급하는 크리덴셜 단위. 클럽 1개에 묶입니다.
  • 인증 = OAuth2 client_credentials. 장수명 정적 키는 없습니다 — client_secret으로 15분 ES256 토큰을 받아 씁니다.
  • 표면 = https://openapi.kolleges.net/v2/clubs/{clubDomain}/…. clubDomain은 경로에서만 (예외: GET /v2/me — 내 클라이언트가 어느 워크스페이스에 묶였는지 알려주는 부트스트랩 라우트).
  • 응답 = { data }(단건) · { data, meta }(커서 목록) · BatchResultDto(발급 배치). 에러 = RFC 9457 application/problem+json.

  1. 클라이언트 발급 (대시보드, 1회)

    섹션 제목: “클라이언트 발급 (대시보드, 1회)”

    admin-next 사이드바 Developers › “새 클라이언트”:

    • client_id + client_secret을 화면에서 한 번만 복사하세요. 플랫폼은 해시만 보관하며 재열람이 불가합니다. 분실 시 회전(rotate)합니다.
    • scope 선택(deny-by-default·최소권한): clubs:read · billing:read · achievements:read · achievements:manage · designs:read · designs:manage · issuance:read · issuance:write · issuance:revoke · events:read.

  2. 토큰 발급 (매 15분·서버측)

    섹션 제목: “토큰 발급 (매 15분·서버측)”
    Terminal window
    curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
      -d 'grant_type=client_credentials' \
      -d 'scope=kolleges:openapi:issuance:write kolleges:openapi:issuance:read' \
      https://auth.kolleges.net/token
    # → { "access_token": "<ES256 JWT>", "token_type": "Bearer", "expires_in": 900, "scope": "…" }

  3. 내 워크스페이스 확인 (clubDomain 확보)

    섹션 제목: “내 워크스페이스 확인 (clubDomain 확보)”

    다른 모든 경로가 /v2/clubs/{clubDomain}/… 인데 토큰에는 워크스페이스 도메인이 들어 있지 않습니다. GET /v2/me 가 그 값을 알려줍니다 — 경로에 clubDomain 이 없는 유일한 라우트이고, 별도 권한 없이 유효한 토큰이면 호출할 수 있습니다.

    Terminal window
    TOKEN=<access_token>
    

    curl -s -H "Authorization: Bearer $TOKEN" https://openapi.kolleges.net/v2/me
    # → { data: { clientId, clubDomain, operations } }
    

    CLUB=<응답의 clubDomain>

  4. 호출

    섹션 제목: “호출”
    Terminal window
    # 클럽 신원·발급 가능 여부
    curl -s -H "Authorization: Bearer $TOKEN" \
      https://openapi.kolleges.net/v2/clubs/$CLUB/
    # → { data: { domain, name, canIssue, grantedOperations } }

  5. 발급 (bulk·단건=배열 1개)

    섹션 제목: “발급 (bulk·단건=배열 1개)”
    Terminal window
    curl -s -X POST -H "Authorization: Bearer $TOKEN" \
      -H 'Content-Type: application/json' \
      -H "Idempotency-Key: order-2026-07-19-0001" \
      -d '{
            "achievementFormId": 123,
            "mode": "email",
            "recipients": [{ "externalUserId": "u-42", "name": "김철수", "email": "kim@example.com" }]
          }' \
      https://openapi.kolleges.net/v2/clubs/$CLUB/issuances
    # → { results: [{ ref, status: "issued|skipped|failed", resourceId, error }],
    #     summary: { total, ok, skipped, failed } }

  6. 조회·파일·취소·이벤트

    섹션 제목: “조회·파일·취소·이벤트”
    Terminal window
    # 발급 목록(커서)
    curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances?limit=20"
    # 상세(수령자 PII)
    curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances/456"
    # 인증서 파일
    curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances/456/file?format=pdf" -o cert.pdf
    # 취소(= 무효화)
    curl -s -X POST -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/issuances/456/revoke"
    # 이벤트 피드
    curl -s -H "Authorization: Bearer $TOKEN" "https://openapi.kolleges.net/v2/clubs/$CLUB/events?limit=20"

다음 단계

섹션 제목: “다음 단계”

더 알아보기

  • 인증 — 토큰 흐름·scope·키 회전을 자세히.
  • 개념 — issuance·achievement·holder·응답 envelope.
  • 에러 처리 — RFC 9457 problem+json.
  • API 레퍼런스 — 전체 엔드포인트·스키마·인터랙티브 탐색.