자격 증명 API

자격 증명(assertion)을 생성하고 관리해요. 자격 증명은 특정 수령자에게 발급된 배지예요.

모든 엔드포인트는 X-Api-Key 헤더를 통한 인증이 필요해요. 인증을 참고하세요.

자격 증명 생성

수령자에게 배지를 발급해요.

사람마다 API를 한 번씩 호출하는 대신 수백, 수천 명에게 한 번에 발급해야 한다면, CSV 업로드를 지원하는 대량 자격 증명 UI 기능을 사용하세요.

POST /awards

매개변수

매개변수	타입	필수	설명
badgeId	string	예	발급할 배지 ID
recipient	object	예	수령자 상세 정보 (아래 참고)
recipient.name	string	예	수령자 전체 이름 (최소 5자)
recipient.email	string	예	수령자 이메일 주소
issuedOn	string	예	ISO 8601 형식의 발급일 (예: 2025-01-15)
expires	string	아니요	ISO 8601 형식의 만료일

예시

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

응답

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

참고

• 연간 자격 증명 풀에서 자격 증명 1개로 계산돼요 (Free: 연 1,200개, Starter: 연 12,000개, Pro: 연 120,000개). 이 풀은 유연한 연간 허용량이라 1년 중 언제든, 한꺼번에 몰아서도 쓸 수 있으며, 계정 가입 기념일에 초기화돼요. 청구는 계속 월 단위이고, 자격 증명 할당량만 연 단위예요. 자세한 내용은 요금제 및 청구를 참고하세요.

---

자격 증명 목록 조회

선택적 필터링과 페이지 나누기로 자격 증명을 조회해요.

GET /awards

쿼리 매개변수

매개변수	타입	필수	설명
filter	JSON string	아니요	필터 객체 (아래 참고)
lastEvaluatedKey	string	아니요	이전 응답에서 받은 페이지 나누기 토큰

필터 객체

filter 매개변수는 다음 필드가 담긴 JSON 문자열을 받아요.

필드	타입	설명
badgeId	string	배지 ID로 필터링해요.
search	string	수령자 이름 또는 이메일에서 찾을 부분 문자열이에요 (searchField 참고).
searchField	string	name(기본값) 또는 email 중 하나로, 검색할 열을 지정해요.

lastEvaluatedKey를 통한 페이지 나누기는 필터 사용 여부와 관계없이 동작해요. 페이지 크기는 50이에요.

예시 — 모든 자격 증명 조회

curl -X GET https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here"

예시 — 배지로 필터링

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

응답

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

응답에 lastEvaluatedKey가 있으면 결과가 더 있다는 뜻이에요. 다음 페이지를 가져오려면 다음 요청에서 이를 쿼리 매개변수로 전달하세요.

---

자격 증명 이메일 보내기

수령자에게 자격 증명에 대한 이메일 알림을 보내요.

POST /awards/{awardId}/send

매개변수

매개변수	타입	필수	설명
awardId	string	예	어워드 ID (경로 매개변수 및 본문)
email	string	예	수령자 이메일 주소

예시

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

응답

일반 확인 문자열을 반환해요.

"email sent"

---

자격 증명 공유

여러 수신자에게 이메일로 자격 증명을 공유해요.

POST /awards/{awardId}/share

매개변수

매개변수	타입	필수	설명
awardId	string	예	어워드 ID (경로 매개변수 및 본문)
recipients	string	예	쉼표로 구분한 이메일 주소 목록
subject	string	예	이메일 제목
message	string	예	이메일 본문

예시

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

응답

일반 확인 문자열을 반환해요.

"email sent"

---

자격 증명 취소

발급한 자격 증명을 취소해요. 호스팅된 Open Badges v2.0 assertion에 revoked: true(선택적 사유 포함)가 표시되어 모든 검증 도구가 해당 배지가 더 이상 유효하지 않음을 알 수 있어요. 자격 증명 레코드는 감사 목적으로 보관되며 크레딧은 환불되지 않아요.

취소는 해당 자격 증명의 Open Badges 3.0 Verifiable Credential에도 전파돼요. VC의 credentialStatus가 참조하는 W3C Bitstring Status List에서 해당 어워드의 비트가 뒤집히므로 VC 지갑에서도 취소를 감지해요. 취소 (Bitstring Status List)를 참고하세요.

POST /awards/{awardId}/revoke

매개변수

매개변수	타입	필수	설명
awardId	string	예	어워드 ID (경로 매개변수)
reason	string	아니요	취소 사유예요. 500자로 잘려요.
notify	boolean	아니요	true이면 수령자에게 자격 증명이 취소되었다는 이메일을 보내요. 기본값은 false예요.

예시

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

응답

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

이미 취소된 자격 증명을 다시 취소해도 멱등적으로 동작해요. 알림을 다시 보내지 않고 같은 응답을 반환해요.

대량 취소

많은 자격 증명을 한 번에 취소하려면, 어워드마다 이 엔드포인트를 호출하는 대신 action: "revoke"를 지정한 내구성 있는 대량 엔드포인트를 사용하세요.

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

{ "jobId", "total" }을 반환해요. 작업은 서버 측에서 모든 ID를 취소하며(이미 취소된 것은 건너뜀) 이어서 실행할 수 있어요. 이미 취소되었거나 존재하지 않는 ID는 건너뜀으로 보고돼요.

---

자격 증명 삭제

발급한 자격 증명을 완전히 삭제해요. 취소와 달리 레코드가 완전히 제거되며 공개 자격 증명 페이지는 404를 반환해요. 실제 실수(예: 엉뚱한 사람에게 발급)에만 사용하고, 실제 자격 증명은 assertion이 취소된 상태로 계속 검증될 수 있도록 취소를 사용하는 것이 좋아요. 크레딧은 환불되지 않아요.

DELETE /awards/{awardId}

매개변수

매개변수	타입	필수	설명
awardId	string	예	어워드 ID (경로 매개변수)

예시

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

응답

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

PDF 인증서 다운로드

자격 증명의 인쇄용 A4 PDF 인증서를 생성해요.

GET /certify-badge/award/{awardGuid}/pdf

인증이 필요 없어요. 이 엔드포인트는 수령자가 직접 인증서를 다운로드할 수 있도록 공개되어 있어요.

예시

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

응답은 Content-Type: application/pdf 헤더가 붙은 바이너리 PDF예요.

---

자격 증명 이벤트 추적

참여 이벤트를 기록해요. 공개 자격 증명 페이지가 참여 통계를 채우는 데 사용해요. 인증이 필요 없어요.

POST /certify-badge/award/{awardGuid}/event

매개변수

이 엔드포인트는 본문을 직접 읽어요 (parameters 래퍼 없음).

매개변수	타입	필수	설명
event	string	예	view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify 중 하나예요.
network	string	아니요	event=share일 때의 소셜 네트워크: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP별 중복 제거: 같은 IP에서 발생한 동일한 이벤트는 24시간에 한 번만 집계돼요.

예시

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

응답

{
  "ok": true
}

---

자격 증명 통계 조회

자격 증명의 누적 참여 카운터를 조회해요.

GET /certify-badge/award/{awardGuid}/stats

인증이 필요 없어요.

응답

카운터는 원시 이벤트 유형을 키로 반환돼요. totals에는 이벤트별 총 횟수가, networks에는 network를 갖는 이벤트(현재는 share)의 네트워크별 분포가 담겨요. 기록된 활동이 없는 이벤트는 그냥 빠져 있어요.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}