API 소개

1Badge 개발자 센터는 1Badge가 제공하는 다양한 서비스를 연동하여 디지털 인증서의 발급·검증·관리를 자동화하려는 개발자를 위한 공식 문서입니다. 배지의 조회·발급·회수 기능을 REST API로 제공합니다.

• 표준 — Open Badges 3.0 / W3C Verifiable Credentials 2.0
• 형식 — 요청·응답 모두 JSON을 사용하며, 필드 네이밍은 snake_case 입니다.
• 인증 — 모든 요청에 X-API-Key 헤더를 사용합니다.

빠르게 시작하기

1Badge API 사용이 처음이시라면, 아래 순서를 따라 첫 API 호출을 경험해보세요. API Key 발급부터 인증, 첫 응답 확인까지 순서대로 안내합니다.

1. API Key 발급 받기

발급받은 기관 계정으로 API Key를 준비합니다. 발급 방법과 관리 주의사항은 인증 문서를 참고하세요.

2. 첫 API 호출하기

ping 엔드포인트로 API Key가 유효한지 확인하여 첫 200 OK 응답을 받아봅니다. 실제 데이터를 조회하기 전, 인증만 먼저 점검하는 용도입니다.

curl https://api.1badge.world/api/v1/ext/ping \
  -H "X-API-Key: {발급받은_API_Key}"

{
  "code": "0001",
  "message": "정상 처리되었습니다.",
  "data": { "status": "ok", "apikey_prefix": "bd_live_" }
}

3. 발급·회수 연동하기

발급·회수 흐름에서 비동기 처리 방식과 상태 모델을 익힌 뒤, 실제 배지 발급을 연동합니다.

Endpoint(Base URL)·인증·응답 형식 등 공통 규약은 REST API 사용 및 에러 안내를 참고하세요.

제공 기능

구분	엔드포인트
인증키 확인	GET /ping
배지유형 조회	GET /badge-types
카테고리 조회	GET /categories, GET /categories/{category_id}
템플릿 조회	GET /badge-templates, GET /badge-templates/{template_id}
발급	POST /badges, POST /badges/batch
발급이력·상세	GET /badges/history, GET /badges/{badge_id}
회수	POST /badges/revoke

조회 전용 안내

카테고리·템플릿·배지유형의 생성·수정·삭제는 제공하지 않습니다.
해당 항목의 등록·관리는 1Badge 기관용 백오피스에서 작업 바랍니다.

다음 단계

• 인증 — API Key 발급과 요청 인증
• API 요청건수 제한 안내 — Rate Limit·발급 한도·페이지네이션
• 발급·회수 흐름 — 비동기 처리와 상태 모델
• API 에러코드 — 응답 코드와 오류 처리
• API 문서 보기 — 엔드포인트 상세 명세