REDBEAN8
인증 · API 키
모든 API 요청은 API 키로 인증합니다. 키는 API 연동 메뉴에서 발급·폐기합니다.
Bearer 토큰
HTTP
GET /v1/account/balance HTTP/1.1
Host: api-01.redbean8.io.kr
Authorization: Bearer ak_3f9c0b6a1d...(총 51자)- 키 형식은
ak_+ 소문자 16진수 48자(총 51자) 입니다. - 키 원문은 발급 직후 한 번만 표시됩니다. 서버에는 해시만 저장하므로 분실 시 복구할 수 없습니다. 폐기 후 재발급하세요.
- 키는 서버(백엔드)에서만 사용하세요. 브라우저/모바일 앱 코드에 넣지 마세요.
- 회원당 활성 키는 최대 10개입니다. 시스템·용도별로 나누어 발급하면 폐기·교체가 쉽습니다.
키 보안 옵션
| 옵션 | 설명 |
|---|---|
| 허용 IP | 키별로 호출 가능한 IP/CIDR 을 제한합니다. (예: 203.0.113.10, 198.51.100.0/24, 최대 50개) 허용 IP 는 보안을 위해 관리자가 등록·변경하며 회원이 직접 수정할 수 없습니다. 키 발급 후 1:1 문의로 API 서버의 고정 공인 IP 를 알려 주세요. 목록 밖에서 호출하면 403 IP_NOT_ALLOWED, 허용 IP 가 등록되지 않은 키는(필수 정책 적용 시) 403 IP_WHITELIST_REQUIRED. |
| 만료일 | 관리자가 설정합니다. 지정한 일시 이후 자동으로 사용 불가(401 UNAUTHORIZED). 변경이 필요하면 문의해 주세요. |
| 폐기 | 즉시 차단됩니다. (인증 결과 캐시는 폐기 시 함께 삭제) |
| 마지막 사용 | 키 목록에서 마지막 사용 시각·IP 를 확인할 수 있습니다. |
발신번호 API 허용
웹에서 승인된 발신번호라도, API 로 쓰려면 발신번호별로 “API 허용”을 켜야 합니다. 웹 로그인 후 API 연동 화면에서 번호별 스위치로 별도 인증 없이 켜고 끌 수 있습니다.
- 허용되지 않은 번호로 요청하면
403 SENDER_API_NOT_ENABLED. - 미승인/미등록 번호는
422 SENDER_NOT_APPROVED. - 발신번호가 재승인되면 API 허용은 자동으로 해제되며, 다시 켜야 합니다.
- 통신사(KTOA)에서 중지된 번호는
422 SENDER_BLOCKED.
인증 오류
| HTTP | code | 원인 |
|---|---|---|
| 401 | UNAUTHORIZED | 키 누락·오타·폐기·만료. 응답 헤더에 WWW-Authenticate: Bearer 포함 |
| 403 | IP_NOT_ALLOWED | 키의 허용 IP 에 없는 주소에서 호출 |
| 403 | IP_WHITELIST_REQUIRED | 키에 허용 IP 가 등록되지 않음 — 고객센터에 허용 IP 등록 요청 |
| 403 | ACCOUNT_SUSPENDED | 이용이 제한된 계정 |
| 403 | API_DISABLED | 이 계정의 API 사용이 허용되지 않음 (운영 정책) |
| 503 | API_DISABLED | 시스템 점검 등으로 외부 API 가 일시 중단됨 |
| 429 | RATE_LIMITED | 인증 실패가 짧은 시간에 반복된 IP (Retry-After: 60) |
잘못된 키로 반복 호출하면 해당 IP 가 1분간 차단됩니다. 401 을 받으면 재시도하지 말고 키를 점검하세요.
키 유출 시 대응
- API 연동 에서 해당 키를 즉시 폐기합니다.
- 새 키를 발급해 시스템에 교체합니다. (신·구 키를 잠시 병행해 무중단 교체 가능)
- 발송 목록(
GET /v1/messages)에서 의도하지 않은 발송이 없는지 확인합니다.