API 키

API 키를 사용하면 badges.ninja REST API에 프로그래밍 방식으로 접근할 수 있어요. 자신의 애플리케이션에서 배지의 생성, 발급, 관리를 자동화하는 데 사용해 보세요.

API 키 생성

1. 사이드바에서 API 키 페이지를 엽니다.
2. API 키 생성을 클릭하면 인라인 폼이 열려요.

3. 키 이름을 입력하고 생성을 클릭합니다. 전체 키가 녹색 배너에 딱 한 번 표시돼요.

4. 키를 바로 복사하세요 — 전체 키는 한 번만 표시됩니다. 잃어버리면 새로 만들어야 해요. 배너를 닫으면 대시보드에는 키의 접두사(예: bws_a1b2c3d4...)만 표시되며, 전체 키는 요청 인증을 위해 서버 측에 저장됩니다.

각 행에는 키가 생성된 시점도 표시되고, 키를 사용한 뒤에는 마지막 사용 타임스탬프도 표시되어 사용하지 않는 키를 쉽게 찾을 수 있어요.

접근 범위

키를 만들 때 읽기 전용으로 만들거나 전체 접근 권한을 그대로 둘 수 있어요.

범위	허용 내용
전체 접근 (기본값)	읽기 및 쓰기 — 데이터를 조회하고 생성, 발급, 수정, 삭제할 수 있습니다.
읽기 전용	안전한 GET 요청만 가능합니다. 데이터를 변경하는 모든 요청(POST, PUT, PATCH, DELETE)은 403 Forbidden으로 거부됩니다.

데이터를 읽기만 하면 되는 연동(리포팅, 대시보드, 백업)에는 읽기 전용 키를 사용하세요. 키가 유출되어도 아무것도 변경할 수 없어요. 생성 폼에서 읽기 전용 키를 선택하면 되며, 읽기 전용 키는 목록에 읽기 전용 배지가 표시됩니다. 범위 기능이 생기기 전에 만든 키는 전체 접근 권한을 유지해요.

키 형식

API 키는 bws_ 접두사 뒤에 32자리 16진수 문자열이 붙는 형식이에요.

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

요청에서 API 키 사용

모든 API 요청의 X-Api-Key 헤더에 API 키를 포함하세요.

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

API 인증에 대한 자세한 내용은 인증 페이지를 참고하세요.

플랜별 키 한도

만들 수 있는 API 키 수는 플랜에 따라 달라요.

플랜	API 키 한도
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

키 만료

모든 API 키는 생성 후 1년이 지나면 만료됩니다. 키가 만료되면 삭제된 것과 똑같이 더 이상 요청을 인증하지 않아요. 서비스가 중단되지 않도록 기존 키가 만료되기 전에 새 키를 만드세요.

키 삭제

1. API 키 페이지를 엽니다.
2. 삭제할 키를 찾습니다.
3. 삭제를 클릭합니다.
4. 삭제를 확인합니다.

삭제하면 키는 즉시 작동하지 않아요. 해당 키를 사용하는 애플리케이션은 인증 오류를 받게 됩니다.