API 클라이언트 만들기

핵심요약

개발자 메뉴에서 이름과 권한을 정해 API 클라이언트를 만들면, 기관 시스템에서 칼리지스 API로 인증서를 발급하거나 조회할 수 있습니다. 시크릿은 생성 직후 한 번만 보이니 바로 저장해야 합니다.

필요 권한 워크스페이스 관리 권한이 있는 담당자

언제 필요한가요

학사 시스템이나 LMS에서 수료가 확정될 때 자동으로 배지를 발급하고 싶을 때 사용합니다. 관리자 화면에 들어오지 않고도 서버에서 직접 발급·조회를 처리할 수 있습니다. 개발 담당자와 함께 진행하세요.

시작하기 전에

발급받은 시크릿을 안전하게 보관할 곳(사내 비밀 관리 도구 등)을 미리 정해두세요. 시크릿은 생성 직후 한 번만 표시되며 다시 볼 수 없습니다.

1. 클라이언트 만들기

개발자 메뉴에서 [+ API 클라이언트 만들기]를 누르고 아래를 입력하세요.

1. 이름 - 어디에 쓰는 클라이언트인지 알아보기 쉽게 짓습니다(예: 학사시스템 발급 봇)
2. 권한 - 필요한 것만 고릅니다. 화면 안내대로 “최소한의 권한만 선택하세요.”

권한	무엇을 할 수 있나요
인증서 발급	서버에서 인증서를 발급
발급 내역 조회	발급 결과를 조회
발급 취소	발급 건을 무효화
워크스페이스 정보 조회	기관 정보 조회
인증서 양식 조회·관리	인증서 종류 조회·수정
청구 정보 조회	요금·사용량 조회
디자인 조회·관리	배지·증명서 디자인 조회·수정
이벤트 조회	발생한 이벤트 조회

3. [만들기]를 누릅니다.

2. 발급 정보 저장하기

생성 직후 아래 정보가 표시됩니다.

주의: “이번 한 번만 확인할 수 있어요. 안전한 곳에 지금 저장하세요. 창을 닫으면 다시 볼 수 없어요.” 창을 닫기 전에 반드시 모두 복사해 보관하세요.

항목	용도
클라이언트 ID	공개 식별자. 토큰 발급 시 client_id로 사용
API 주소	이 워크스페이스 전용 엔드포인트
클라이언트 시크릿	비밀 값. 이번 한 번만 표시
토큰 발급 엔드포인트	토큰을 받아오는 주소
부여된 scope	토큰 발급 시 반드시 함께 보내야 하는 값

각 항목 옆의 [복사] 버튼으로 옮긴 뒤 [확인했어요]를 누르세요.

완료 확인하기

목록에 새 클라이언트가 활성 상태로 나타나면 완료입니다. 권한과 생성일도 함께 표시됩니다.

만든 뒤 관리하기

목록의 ”⋯” 메뉴에서 세 가지를 할 수 있습니다.

• 테스트 토큰 발급 - 연동이 잘 되는지 확인
• 시크릿 회전 - 시크릿을 새로 발급(기존 값은 무효화)
• 폐기 - 클라이언트를 사용 중지

주의: 폐기하면 이 클라이언트의 토큰이 곧바로 무효화되고 되돌릴 수 없습니다. 폐기한 클라이언트는 지워지지 않고 ‘폐기됨’ 목록에 남습니다. 실수를 막기 위해 클라이언트 이름을 정확히 입력해야 폐기 버튼이 활성화됩니다.

이런 경우에는

시크릿을 저장하지 못하고 창을 닫았어요

다시 볼 수 없습니다. [시크릿 회전]으로 새 값을 발급받아 사용하세요.

API 호출이 403 오류로 실패해요

토큰을 발급할 때 scope를 함께 보냈는지 확인하세요. 생략하면 권한 없는 토큰이 발급되어 모든 호출이 403이 됩니다.

자주 묻는 질문

권한을 나중에 바꿀 수 있나요?

화면 안내에 따르면 기존 클라이언트의 권한을 수정하기보다 새로 만들어 조정하는 방식입니다.

연동 방법은 어디서 확인하나요?

화면 오른쪽 위의 [개발자 문서] 링크 또는 developers.kolleges.net에서 확인할 수 있습니다.

관련 가이드

• 배지·인증서 발급하기 - 화면에서 직접 발급하기
• 멤버 초대·역할 관리하기 - 사람에게 권한 부여하기