인증

badges.ninja API로 보내는 모든 요청에는 인증이 필요합니다. 이 페이지에서는 요청을 어떻게 인증하는지 설명합니다.

기본 URL

https://api.badges.ninja

모든 API 엔드포인트는 이 기본 URL에 대한 상대 경로입니다.

API 키 인증

주된 인증 방식은 X-Api-Key 헤더에 실어 보내는 API 키입니다.

API 키 얻기

대시보드에서:

1. badges.ninja 에 로그인합니다.
2. 사이드바의 API 키 로 이동합니다.
3. API 키 생성 을 클릭합니다.
4. 키를 복사합니다(한 번만 표시됨).

API에서:

Cognito 인증 플로우의 JWT 토큰을 이용해 API로도 API 키를 관리할 수 있습니다. 가장 간단한 방법은 대시보드를 확인하세요.

API 키 사용

모든 요청의 X-Api-Key 헤더에 키를 포함합니다.

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

API 키 형식

키는 bws_ 접두사를 사용합니다.

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

요청 형식

• GET 요청은 파라미터를 쿼리 문자열로 전달합니다
• POST 와 PUT 요청은 parameters 객체를 포함한 JSON 본문을 보냅니다
• 모든 응답은 Content-Type: application/json 의 JSON으로 반환됩니다

POST/PUT 요청 구조

{
  "parameters": {
    "name": "내 배지",
    "description": "샘플 배지"
  }
}

요청 예시

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": "내 조직",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

응답 예시

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/abc123-def456"
  }
}

속도 제한

API 요청에는 속도 제한이 적용됩니다. 한도를 초과하면 429 Too Many Requests 응답을 받게 됩니다. 몇 초 기다렸다가 다시 시도하세요.

공개 엔드포인트

일부 엔드포인트는 인증이 필요하지 않습니다. 이들은 /certify-badge/ 하위의 공개 검증 엔드포인트 로, 누구나 배지 자격을 검증할 수 있게 합니다.