API Key 및 보안
자격 증명을 구분하고 발신 도메인 범위를 제한하며 키를 안전하게 교체·폐기하세요.
1. 두 종류의 Bearer 자격 증명
세션 토큰은 domains, api-keys, webhooks 관리용이며 API Key는 /v1/mail 및 SMTP 비밀번호로 사용됩니다. 계정 비밀번호, 세션 토큰, 언어 쿠키와 다릅니다. GET /v1/apikey/verify는 키만 확인하며 도메인 인증이나 잔여 한도를 보장하지 않습니다.
2. 생성 및 보관
이메일 인증 후 비어 있지 않은 name과 선택 숫자 domain_id로 POST /api-keys를 사용합니다. 전체 key는 201 생성 응답에서만 표시됩니다. 서버 비밀 관리 도구에 보관하고 로그, 스크린샷, 프런트 코드에 남기지 마세요. 목록으로 원문을 복구할 수 없습니다.
| 필드 / 설정 | 타입 / 상태 | 설명 |
|---|---|---|
| name | string | 생성 시 빈 값 불가 |
| domain_id | uint64 | 생성 시 선택 도메인 ID |
| key | string | 생성 응답에만 전체 키 |
| id / key_prefix / status | uint64 / string | 목록 메타데이터, prefix로 인증 불가 |
| allowed_domain_id / last_used_at | uint64 / time | 생략 가능, 항상 null 필드 아님 |
curl -X POST "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"name":"Server integration","domain_id":123}'
curl -X GET "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"
curl -X DELETE "${SMTPDOG_API_ORIGIN}/api-keys/${SMTPDOG_KEY_ID}" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"3. 발신 범위 제한
domain_id를 생략하면 계정의 인증된 도메인에서, 지정하면 해당 도메인에서만 발송할 수 있습니다. 생성 시 소유권과 발송 시 verified를 확인합니다. 키 유효기간, 역할, 기존 키 범위 수정은 지원하지 않습니다. 범위 제한은 소유권 인증이나 남용 검사를 대체하지 않습니다.
4. 교체 및 폐기
새 키 생성, 서비스 설정 변경, 전환 확인 후 DELETE /api-keys/{id}로 이전 키를 폐기하세요. 응답은 본문 없는 204이며 새 요청에서 폐기 키를 사용할 수 없습니다. 기존 키 직접 교체나 원문 복구 API는 없습니다. 세션 토큰을 잘못 사용했다면 재시도 전에 인증 방식을 확인하세요.