인증 · API 키 · DirecTalk API 문서

모든 호출은 API 키로 인증합니다. 세션 쿠키나 OAuth 가 아니라 **키 하나** 이고, 그 키가 어느 회사의 것인지·무엇을 보낼 수 있는지·어디서 부를 수 있는지를 전부 서버가 판정합니다.

키를 싣는 법

둘 중 아무 헤더나 쓰면 됩니다. 효과는 같습니다.

키를 만들 때 보낼 수 있는 채널을 고릅니다. 스코프에 없는 채널로 부르면 8625 로 거절됩니다.

키마다 호출을 허용할 IP 대역을 반드시 지정해야 합니다 (8601). 형식은 CIDR 표기입니다 — 210.99.10.0/24 처럼 씁니다. 목록에 없는 곳에서 부르면 8624 입니다.

모의발송 전용 키를 따로 발급할 수 있습니다. 이 키로는 모의발송만 부를 수 있고 실발송 API 는 8626 으로 거절됩니다. 개발 환경에는 샌드박스 키를 두면, 설정 실수로 진짜 메시지가 나가는 사고를 구조적으로 막을 수 있습니다.

아래 코드들은 요청 본문을 검사하기 전에 나옵니다. 본문이 아무리 옳아도 여기서 막히면 컨트롤러에 닿지 않습니다.

코드	HTTP	설명
8620	401	API 키가 필요합니다. Authorization: Bearer {key} 또는 X-Api-Key 헤더로 전달해 주세요.
8621	401	유효하지 않은 API 키입니다.
8622	401	정지된 API 키입니다. 콘솔에서 상태를 확인해 주세요.
8623	401	만료된 API 키입니다.
8624	403	허용되지 않은 IP 에서의 호출입니다. 국외 IP 는 예외 없이 차단됩니다.
8625	403	이 키에 허용되지 않은 발송 채널입니다.
8626	403	샌드박스 키로는 실발송 API 를 호출할 수 없습니다. 모의발송은 /v1/sandbox/messages 를 사용해 주세요.
8627	409	같은 Idempotency-Key 로 이미 접수된 발송이 있습니다.
8628	429	호출 한도를 초과했습니다. 잠시 후 다시 시도해 주세요.
8629	404	발송 그룹을 찾을 수 없습니다.