인증

애플리케이션은 Wink 및 TripPay API와 통신할 수 있는 인증된 OAuth2 세션을 생성하는 데 필요한 Client ID와 Secret Key를 제공합니다.

인증된 세션을 생성하는 단계는 다음과 같습니다.

1단계. 스테이징 또는 프로덕션 환경에서 액세스 토큰을 가져옵니다:

대부분의 경우, 언어별로 강력한 OAuth2 라이브러리를 사용하여 모든 복잡한 작업을 처리할 것입니다. 예제는 curl을 사용한 가장 기본적인 명령줄 사용법을 보여줍니다.

스테이징

curl -X POST https://staging-iam.wink.travel/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_SECRET_KEY>"

프로덕션

curl -X POST https://iam.wink.travel/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_SECRET_KEY>"

이 명령은 액세스 토큰과 기타 OAuth2 응답 데이터를 반환합니다:

{
  "access_token": "abc123"
}

우리의 어떤 엔드포인트에 호출할 때도 헤더에 다음을 포함하세요:

Wink-Version = 2.0 최신 버전 - 다른 사용 가능한 버전은 API 문서를 참조하세요.
Authorization = Bearer ${access_token} 액세스 토큰을 삽입하세요.

권한 범위(Scopes)

**스코프(scope)**는 액세스 토큰이 가진 권한입니다. 토큰을 요청할 때 scope 매개변수에 공백으로 구분된 스코프 목록을 전달하며, 토큰은 해당 스코프가 허용하는 영역에만 접근할 수 있습니다. client_credentials 그랜트에서는 토큰 요청 시 스코프를 설정합니다 — 위의 curl 예제와 Postman 안내를 참고하세요.

스코프 이름은 section.action 형식이며, 액션은 다음 중 하나입니다:

read — 리소스 조회 (안전한 GET 요청)
write — 리소스 생성 및 수정 (POST / PUT / PATCH)
remove — 리소스 삭제 (DELETE)

Wink는 권한을 기능 영역별로 그룹화합니다. 통합에 필요한 스코프만 요청하세요:

스코프 그룹	스코프	허용하는 기능	위험도
Account	`account.read` `account.write` `account.remove`	엔터티, 팀원, 설정, 애플리케이션 관리	낮음–중간
Inventory	`inventory.read` `inventory.write` `inventory.remove`	숙소, 객실 유형, 요금제, 요금, 추가 옵션, 가용성, 액티비티, 명소	낮음–중간
Booking	`booking.read` `booking.write` `booking.remove`	예약 검색, 조회, 생성, 취소, 환불; 체크아웃; 취소 정책	낮음–중간
Marketing	`marketing.read` `marketing.write` `marketing.remove`	캠페인, 혜택, 판매 채널, WinkLinks, 관리형 소셜, 로열티	낮음–중간
Content	`content.read` `content.write` `content.remove`	숙소 설명, 리뷰, 미디어, 지도, 친환경 지수	낮음–중간
Analytics	`analytics.read` `analytics.write` `analytics.remove`	보고 및 분석 — 수익, 리더보드	낮음–중간
Integrations	`integrations.read` `integrations.write` `integrations.remove`	채널 매니저, 외부 예약 시스템, Google Hotel, 알림 엔드포인트, 예약 동기화	낮음–중간
Payment	`payment.read` `payment.write` `payment.remove`	결제 처리, Stripe, Revolut, 지급, 구독	중간–높음
Accounting	`accounting.read` `accounting.write` `accounting.remove`	회계, 출금 원장, 조정	중간–높음
MCP	`mcp.read` `mcp.write` `mcp.remove`	AI 에이전트를 위한 MCP 전송 (`/mcp`) 열기	낮음–중간

몇 가지 유의사항:

최소한으로 요청하세요. 통합에서 실제로 사용하는 스코프만 요청하세요 — 불필요하게 넓은 권한을 가진 토큰은 유출 시 피해 범위가 커집니다.
알 수 없는 스코프는 거부됩니다. 등록되지 않았거나 존재하지 않는 스코프를 요청하면 토큰 발급이 실패합니다.
mcp.*는 AI 에이전트 클라이언트 전용입니다. MCP 전송을 열기 위해 필요하며, 일반 REST API 호출에는 필요하지 않습니다. 자세한 내용은 Model Context Protocol을 참조하세요.