API 키

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

API 키 생성

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

3. 키에 이름을 지정하고 생성 을 클릭합니다. 전체 키는 녹색 배너에 단 한 번만 표시됩니다.

4. 즉시 키를 복사하세요 — 한 번만 표시됩니다. 잃어버리면 새로 만들어야 합니다. 배너를 닫고 나면 접두사만 저장됩니다.

액세스 범위

키를 생성할 때 읽기 전용 으로 만들거나 전체 액세스로 둘 수 있습니다:

범위	허용
전체 액세스(기본값)	읽기 및 쓰기 — 데이터 조회와 생성, 발급, 수정, 삭제.
읽기 전용	안전한 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/월)	5
Pro ($29/월)	20

키 삭제

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

삭제되면 키는 즉시 동작을 멈춥니다. 해당 키를 사용 중인 모든 애플리케이션은 인증 오류를 받게 됩니다.