# API 키와 인증

> 프로젝트 API 키 발급, 권한, 보관과 교체

문서: https://sendwich.kr/docs/api/authentication/

## 키 발급

프로젝트의 **API 키 → 새 키 만들기**에서 발급합니다. 실제 SMS 프로젝트의 키는 `veri_live_`로 시작하며, 전체 값은 발급 시 한 번만 표시됩니다.

```http
Authorization: Bearer YOUR_LIVE_SECRET_KEY
```

키는 서버의 비밀 환경변수에 보관합니다. 브라우저에 공개되는 `NEXT_PUBLIC_`, `VITE_` 환경변수에는 저장하지 않습니다.

## 프로젝트와 권한

API 키가 속한 프로젝트와 환경에서 인증을 생성·조회·취소할 수 있습니다.

| 권한 | 기능 |
| --- | --- |
| `verifications:create` | 인증 생성 |
| `verifications:read` | 인증 상태와 결과 조회 |
| `verifications:cancel` | 인증 취소 |

대시보드에서 발급하는 키에는 세 권한이 모두 포함됩니다. 권한이 부족한 요청은 `403 insufficient_scope`를 반환하며, 폐기된 키로는 API를 호출할 수 없습니다.

## 키와 토큰의 용도

| 항목 | 용도 | 보관 위치 |
| --- | --- | --- |
| 프로젝트 API 키 | API 요청 인증 | 서비스 서버 |
| 웹훅 서명 키 (`whsec_…`) | 수신한 이벤트의 서명 검증 | 웹훅 수신 서버 |
| 인증 창 URL의 세션 토큰 | 해당 인증 창 접근 | 인증을 시작한 사용자에게 전달 |

인증 코드, 세션 토큰, 전체 전화번호는 공개 메시지나 운영 로그에 기록하지 않습니다. `state`와 `client_reference`에는 개인정보 대신 임의의 식별자를 사용합니다.

## 키 교체

새 키 발급 → 서버에 적용 → API 요청 확인 → 이전 키 폐기 순서로 교체합니다. 기존 인증은 같은 프로젝트의 새 키로 조회할 수 있습니다. 분실한 키는 재발급하고, 외부에 노출된 키는 즉시 폐기합니다.