콘텐츠로 이동
Kolleges Developers

Quickstart

kolleges를 API로 자동화하려는 직접 고객(자기 클럽의 데이터컨트롤러)을 위한 시작 가이드입니다. 정본 계약 = Open API v2 레퍼런스. 여러 클럽을 대행 운영하는 채널 파트너라면 별도의 Partner API 레퍼런스(호스트 partner.kolleges.net)를 참조하세요.

한 장 개념

섹션 제목: “한 장 개념”
  • API 클라이언트(apiClient) = 대시보드에서 발급하는 크리덴셜 단위. 클럽 1개에 묶입니다.
  • 인증 = OAuth2 client_credentials. 장수명 정적 키는 없습니다 — client_secret으로 15분 ES256 토큰을 받아 씁니다.
  • 표면 = https://openapi.kolleges.net/v2/clubs/{clubDomain}/…. clubDomain은 경로에서만.
  • 응답 = { 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. 호출

    섹션 제목: “호출”
    Terminal window
    TOKEN=<access_token>
    CLUB=<clubDomain>
    

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

  4. 발급 (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 } }

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

    섹션 제목: “조회·파일·취소·이벤트”
    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 레퍼런스 — 전체 엔드포인트·스키마·인터랙티브 탐색.