발급자 API

배지를 발급하는 조직 또는 개인인 배지 발급자를 관리해요.

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

발급자 생성

새 배지 발급자를 생성해요.

POST /issuers

파라미터

파라미터	타입	필수	설명
name	string	예	조직 이름(최소 3자)
url	string	예	조직 웹사이트(올바른 HTTP/HTTPS URL이어야 함)
email	string	예	발급자의 연락처 이메일
logo	string	아니요	Base64로 인코딩된 이미지(PNG 또는 JPG)
linkedinOrganizationId	string	아니요	숫자 형식의 LinkedIn 회사 페이지 ID. 설정하면 이 발급자의 모든 공개 자격 증명 페이지에 Add to LinkedIn Profile 버튼이 표시돼요.

예시

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

응답

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

참고

• 요금제의 발급자 한도에 포함돼요(Free: 2개, Starter: 5개, Pro: 10개). 할당량은 차감되지 않아요.
• 발급자 이메일이 계정 이메일과 같으면 발급자가 자동으로 검증돼요.
• 이메일이 다르면 발급자 이메일로 검증 메일이 발송돼요.
• 발급자를 설정한 뒤에는 자격 증명 API를 사용해 해당 발급자 아래에서 자격 증명을 발급할 수 있어요.

---

발급자 목록

생성한 모든 발급자를 조회해요.

GET /issuers

예시

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

응답

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp는 밀리초 단위의 Unix 에포크예요. 발급자가 한 페이지에 담기는 수보다 많으면 페이지네이션을 위한 lastEvaluatedKey도 함께 반환돼요.

---

발급자 검증

이메일로 전송된 검증 코드를 사용해 발급자를 검증해요.

POST /issuers/{issuerId}/verify

파라미터

파라미터	타입	필수	설명
issuerId	string	예	발급자 ID(경로 파라미터)
code	string	예	이메일로 받은 검증 코드

예시

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

응답

단순 문자열이에요.

"issuer has been verified"

---

발급자 삭제

발급자를 삭제해요. 발급자에 연결된 배지가 없어야 해요.

DELETE /issuers/{issuerId}

예시

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

응답

단순 문자열이에요.

"issuer has been deleted"

오류

• 400 — 발급자에 아직 연결된 배지가 있음: issuer has {n} badge(s) linked — delete the badges first. 삭제는 연결된 배지만 기준으로 제한되며, 자격 증명은 삭제를 막지 않아요.
• 404 — 발급자를 찾을 수 없음

---

발급자 업데이트

발급자의 필드를 업데이트해요. 검증되지 않은 발급자만 수정할 수 있어요. 발급자가 검증되면 자격 증명의 안정성을 유지하기 위해 이 엔드포인트는 400 verified issuers cannot be edited를 반환해요. 발급자를 수정하면 검증 코드가 다시 생성돼요. email이 계정 이메일과 같으면 발급자가 자동으로 다시 검증되고, 그렇지 않으면 해당 주소로 새 검증 메일이 발송돼요.

PUT /issuers/{issuerId}

파라미터

파라미터	타입	필수	설명
issuerId	string	예	발급자 ID(경로 파라미터)
name	string	아니요	새 이름
url	string	아니요	새 URL
email	string	아니요	새 이메일(계정 이메일과 같지 않으면 새 검증 메일이 발송돼요)
logo	string	아니요	Base64로 인코딩된 새 로고
linkedinOrganizationId	string	아니요	새 LinkedIn 조직 ID(비우려면 빈 문자열)

응답

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

오류

• 400 — verified issuers cannot be edited (발급자가 이미 검증됨)
• 400 — not authorized (다른 계정에 속한 발급자)
• 404 — 발급자를 찾을 수 없음