카카오싱크 API

이 문서는 게임플레이 파트너사의 연동에 필요한 카카오디벨로퍼스 공식 가이드 내용을 요약한 안내입니다.
실제 구현 전 반드시 카카오싱크 개발 가이드에서 전체 연동 흐름을, 카카오 로그인 REST API 공식 가이드에서 최신 요청·응답 규격과 제약사항을 확인하세요.

관련 가이드: 카카오싱크 설정에서 비즈 앱, 채널, 동의항목, 서비스 약관 설정을 먼저 완료하세요.

카카오톡 게임웹뷰에서 카카오싱크 간편가입과 파트너사 로그인을 처리하는 REST API 스펙입니다.
게임 URL 진입 즉시 인가 코드를 요청하고, 앱 미동의 사용자에게는 동의 화면을 표시하며 동의 완료 사용자에게는 별도 버튼 없이 서비스 세션을 발급하는 흐름을 기준으로 합니다.

API 목록

API	Method · URL	적용 여부
인가 코드 요청	`GET https://kauth.kakao.com/oauth/authorize`	필수
토큰 발급	`POST https://kauth.kakao.com/oauth/token`	필수
사용자 정보 조회	`GET https://kapi.kakao.com/v2/user/me`	필수
서비스 약관 동의 내역 조회	`GET https://kapi.kakao.com/v2/user/service_terms`	필수
토큰 갱신	`POST https://kauth.kakao.com/oauth/token`	필수
액세스 토큰 정보 조회	`GET https://kapi.kakao.com/v1/user/access_token_info`	선택

연결 해제는 파트너사가 직접 호출하는 API가 아니라 계정 상태 변경 웹훅 연동으로 처리됩니다. 자세한 내용은 아래 연결 해제를 참고하세요.

채널 친구 상태를 서비스 기능에 사용한다면 카카오톡 채널 관계 조회 API를 추가로 연동합니다.

공통

호출 도메인

도메인	용도
`https://kauth.kakao.com`	인가 코드, 토큰 발급과 갱신을 처리하는 인증 서버입니다.
`https://kapi.kakao.com`	사용자 정보, 서비스 약관, 연결 상태를 처리하는 API 서버입니다.

인증 정보 보관

REST API 키와 클라이언트 시크릿은 파트너사 서버에서만 사용합니다.
액세스 토큰과 리프레시 토큰은 파트너사 서버에 안전하게 저장합니다.
어드민 키를 게임웹뷰의 HTML이나 브라우저 요청에 포함하지 않습니다.
카카오 회원번호(id)를 파트너사 회원의 고정 매핑 키로 사용합니다.
이메일과 전화번호는 변경될 수 있으므로 고정 식별자로 사용하지 않습니다.

가입·로그인 처리 순서

게임 URL 진입 즉시 prompt 없이 인가 코드를 요청합니다.
앱 미동의 사용자는 카카오싱크 동의 화면을 완료하고, 동의 완료 사용자는 화면 전환 없이 인가 코드를 받습니다.
파트너사 서버가 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환합니다.
사용자 정보와 서비스 약관 동의 내역을 조회합니다.
카카오 회원번호로 기존 회원을 찾거나 신규 회원을 생성합니다.
파트너사 서비스 세션을 생성한 뒤 게임을 실행합니다.

카카오 토큰 발급만으로 파트너사 로그인이 완료되지는 않습니다.
회원 등록 또는 기존 회원 매핑과 파트너사 서비스 세션 생성까지 직접 구현해야 합니다.

인가 코드 요청

게임 URL이 로드되면 로그인 버튼을 표시하지 않고 이 요청으로 바로 리디렉션합니다.

http

GET https://kauth.kakao.com/oauth/authorize

Request Query

이름	타입	입력값	적용 여부
`client_id`	`String`	파트너사 앱 REST API 키	필수
`redirect_uri`	`String`	디벨로퍼스 앱에 등록한 Redirect URI	필수
`response_type`	`String`	`code` 고정	필수
`state`	`String`	요청별로 생성한 예측 불가능한 값	필수
`scope`	`String`	추가 동의가 필요한 동의항목 ID를 쉼표로 연결	선택
`service_terms`	`String`	추가 동의가 필요한 서비스 약관 태그를 쉼표로 연결	선택

state는 카카오 API 기준 선택 파라미터지만 게임플레이 연동에서는 CSRF 방지를 위해 반드시 사용합니다.
콜백에서 요청 세션에 저장한 값과 응답 값을 비교하고 일치하지 않으면 요청을 중단하세요.

prompt=none을 사용하지 않습니다

prompt=none은 로그인이나 동의처럼 사용자 동작이 필요할 때 UI를 표시하지 않고 오류를 반환합니다.
게임플레이는 앱 미동의 사용자에게 카카오싱크 동의 화면을 바로 표시해야 하므로 인가 코드 요청에서 prompt 파라미터를 보내지 않습니다.

text

https://kauth.kakao.com/oauth/authorize
  ?response_type=code
  &client_id=${REST_API_KEY}
  &redirect_uri=${ENCODED_REDIRECT_URI}
  &state=${STATE}

사용자 상태별 동작

사용자 상태	카카오 화면	결과
앱 미동의	카카오싱크 동의 화면 표시	동의 완료 후 `code` 반환
앱 동의 완료	별도 화면 없음	즉시 `code` 반환
동의 화면 취소	게임 미실행 처리	`error=access_denied` 반환

Response Query

이름	타입	설명	제공 여부
`code`	`String`	토큰 발급에 사용할 일회용 인가 코드	성공 시
`state`	`String`	요청에 전달한 값	요청에 전달한 경우
`error`	`String`	실패 사유 코드	실패 시
`error_description`	`String`	실패 사유 설명	실패 시

http

HTTP/1.1 302 Found
Location: https://partner.example.com/oauth/kakao/callback?code=${AUTHORIZE_CODE}&state=${STATE}

인가 코드는 한 번만 사용할 수 있습니다.
토큰 발급에 실패하면 같은 코드를 재사용하지 말고 인가 코드 요청부터 다시 시작합니다.

토큰 발급

Redirect URI로 받은 인가 코드를 파트너사 서버에서 토큰으로 교환합니다.

http

POST https://kauth.kakao.com/oauth/token
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request Body

이름	타입	입력값	적용 여부
`grant_type`	`String`	`authorization_code` 고정	필수
`client_id`	`String`	파트너사 앱 REST API 키	필수
`redirect_uri`	`String`	인가 코드 요청에 사용한 Redirect URI	필수
`code`	`String`	콜백으로 받은 인가 코드	필수
`client_secret`	`String`	REST API 키의 클라이언트 시크릿	기능 활성화 시 필수

bash

curl -X POST 'https://kauth.kakao.com/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=${REST_API_KEY}' \
  --data-urlencode 'redirect_uri=${REDIRECT_URI}' \
  --data-urlencode 'code=${AUTHORIZE_CODE}' \
  --data-urlencode 'client_secret=${CLIENT_SECRET}'

Response Body

이름	타입	설명	제공 여부
`token_type`	`String`	`bearer` 고정	항상
`access_token`	`String`	카카오 API 호출에 사용하는 액세스 토큰	항상
`expires_in`	`Integer`	액세스 토큰 만료 시간(초)	항상
`refresh_token`	`String`	액세스 토큰 갱신에 사용하는 토큰	항상
`refresh_token_expires_in`	`Integer`	리프레시 토큰 만료 시간(초)	항상
`scope`	`String`	사용자가 동의한 동의항목 ID 목록. 여러 개이면 공백으로 연결됩니다	조건부

json

{
  "token_type": "bearer",
  "access_token": "${ACCESS_TOKEN}",
  "expires_in": 43199,
  "refresh_token": "${REFRESH_TOKEN}",
  "refresh_token_expires_in": 5184000,
  "scope": "profile_nickname profile_image"
}

사용자 정보 조회

액세스 토큰으로 사용자의 카카오 회원번호와 동의한 사용자 정보를 조회합니다.

http

GET https://kapi.kakao.com/v2/user/me
Authorization: Bearer ${ACCESS_TOKEN}
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request Query

이름	타입	설명
`secure_resource`	`Boolean`	프로필 이미지 URL의 HTTPS 사용 여부
`property_keys`	`String[]`	응답에 포함할 사용자 정보 키 목록

bash

curl -G 'https://kapi.kakao.com/v2/user/me' \
  -H 'Authorization: Bearer ${ACCESS_TOKEN}' \
  --data-urlencode 'secure_resource=true' \
  --data-urlencode 'property_keys=["kakao_account.profile"]'

Response Body

이름	타입	설명	제공 여부
`id`	`Long`	파트너사 앱 안에서 사용자를 식별하는 카카오 회원번호	항상
`connected_at`	`Datetime`	앱과 연결된 시각	조건부
`synched_at`	`Datetime`	카카오싱크 간편가입을 완료한 시각	조건부
`kakao_account`	`Object`	사용자가 동의한 카카오계정 정보. 전체 필드는 kakao_account 참고	조건부
`properties`	`Object`	앱에서 관리하는 사용자 프로퍼티	조건부

json

{
  "id": 123456789,
  "connected_at": "2026-08-12T01:23:45Z",
  "synched_at": "2026-08-12T01:23:45Z",
  "kakao_account": {
    "profile_nickname_needs_agreement": false,
    "profile_image_needs_agreement": false,
    "profile": {
      "nickname": "게임플레이 사용자",
      "thumbnail_image_url": "https://example.kakaocdn.net/profile-thumbnail.jpg",
      "profile_image_url": "https://example.kakaocdn.net/profile.jpg"
    }
  }
}

동의항목을 필수 동의로 설정했더라도 사용자의 카카오계정에 값이 없으면 응답에 포함되지 않을 수 있습니다.
각 *_needs_agreement 값이 true이면 해당 정보는 사용자의 추가 동의 후 제공할 수 있습니다.

서비스 약관 동의 내역 조회

간편가입에 등록한 필수 서비스 약관에 모두 동의했는지 확인합니다.

http

GET https://kapi.kakao.com/v2/user/service_terms
Authorization: Bearer ${ACCESS_TOKEN}

Request Query

이름	타입	설명
`result`	`String`	`agreed_service_terms` 또는 `app_service_terms`
`tags`	`String`	조회할 서비스 약관 태그를 쉼표로 연결한 값. 서비스 약관 설정에 등록한 태그입니다

간편가입 완료 여부는 사용자 정보 조회 응답의 synched_at으로 먼저 확인할 수 있습니다.
값이 있으면 카카오싱크 간편가입을 거친 사용자입니다.

다만 synched_at은 가입 시점의 기록이므로 이후 필수 약관을 추가했다면 기존 사용자도 값이 남아 있습니다.
현재 시점의 필수 약관 동의 상태는 result=app_service_terms로 앱의 사용 중인 약관 전체를 조회하고 각 필수 약관의 agreed 값으로 확인합니다.

bash

curl -G 'https://kapi.kakao.com/v2/user/service_terms' \
  -H 'Authorization: Bearer ${ACCESS_TOKEN}' \
  --data-urlencode 'result=app_service_terms'

Response Body

이름	타입	설명	제공 여부
`id`	`Long`	카카오 회원번호	항상
`service_terms`	`ServiceTerms[]`	서비스 약관 동의 내역	조건부

ServiceTerms

이름	타입	설명	제공 여부
`tag`	`String`	간편가입 설정에 등록한 약관 태그	항상
`required`	`Boolean`	필수 약관 여부	항상
`agreed`	`Boolean`	사용자 동의 여부	항상
`revocable`	`Boolean`	동의 철회 가능 여부	항상
`agreed_at`	`Datetime`	마지막 동의 시각	조건부
`agreed_by`	`String`	`KAUTH` 또는 `KAPI` 동의 경로	조건부

tag는 디벨로퍼스에 등록한 서비스 약관과 API 조회 결과를 연결하는 식별자입니다.
파트너사 서버에 저장한 약관 태그와 응답의 tag를 비교해 동의 상태를 판단합니다.
운영 중 디벨로퍼스의 약관 태그를 임의로 변경하면 기존 사용자의 동의 상태를 정확히 판단할 수 없으므로 서버에 저장한 값과 동일하게 유지하세요.

json

{
  "id": 123456789,
  "service_terms": [
    {
      "tag": "service_terms",
      "required": true,
      "agreed": true,
      "revocable": true,
      "agreed_at": "2026-08-12T01:23:45Z",
      "agreed_by": "KAUTH"
    }
  ]
}

필수 약관의 agreed가 false이거나 목록에 없다면 서비스 회원 가입을 완료하지 않습니다.
필요한 약관 태그를 service_terms에 지정해 인가 코드 요청을 다시 수행하거나 파트너사 자체 약관 동의 화면을 제공합니다.

text

https://kauth.kakao.com/oauth/authorize
  ?response_type=code
  &client_id=${REST_API_KEY}
  &redirect_uri=${ENCODED_REDIRECT_URI}
  &service_terms=${REQUIRED_TERM_TAGS}
  &state=${STATE}

토큰 갱신

액세스 토큰이 만료되기 전 또는 API에서 토큰 만료 응답을 받았을 때 리프레시 토큰으로 갱신합니다.

http

POST https://kauth.kakao.com/oauth/token
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request Body

이름	타입	입력값	적용 여부
`grant_type`	`String`	`refresh_token` 고정	필수
`client_id`	`String`	파트너사 앱 REST API 키	필수
`refresh_token`	`String`	토큰 발급 응답으로 받은 리프레시 토큰	필수
`client_secret`	`String`	REST API 키의 클라이언트 시크릿	기능 활성화 시 필수

bash

curl -X POST 'https://kauth.kakao.com/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=${REST_API_KEY}' \
  --data-urlencode 'refresh_token=${REFRESH_TOKEN}' \
  --data-urlencode 'client_secret=${CLIENT_SECRET}'

Response Body

이름	타입	설명	제공 여부
`token_type`	`String`	`bearer` 고정	항상
`access_token`	`String`	갱신된 액세스 토큰	항상
`expires_in`	`Integer`	액세스 토큰 만료 시간(초)	항상
`refresh_token`	`String`	갱신된 리프레시 토큰	조건부
`refresh_token_expires_in`	`Integer`	갱신된 리프레시 토큰 만료 시간(초)	조건부

리프레시 토큰의 만료 시간이 1개월 이상 남아 있으면 응답에 새 리프레시 토큰이 포함되지 않습니다.
새 값이 포함된 경우에만 기존 리프레시 토큰을 교체하세요.

리프레시 토큰도 만료되었으면 게임 URL 진입 시 수행한 인가 코드 요청부터 다시 시작합니다.

액세스 토큰 정보 조회

액세스 토큰의 앱 ID, 사용자 회원번호, 남은 유효 시간을 확인할 때 사용합니다.
모든 API 호출 전에 선행할 필요는 없으며 운영상 토큰 상태 확인이 필요한 경우에만 사용합니다.

http

GET https://kapi.kakao.com/v1/user/access_token_info
Authorization: Bearer ${ACCESS_TOKEN}

bash

curl -G 'https://kapi.kakao.com/v1/user/access_token_info' \
  -H 'Authorization: Bearer ${ACCESS_TOKEN}'

이름	타입	설명	제공 여부
`id`	`Long`	카카오 회원번호	항상
`expires_in`	`Integer`	액세스 토큰 만료 시간(초)	항상
`app_id`	`Integer`	토큰이 발급된 앱 ID	항상

게임 중 추가 동의

게임 플레이 중 새로운 scope 또는 서비스 약관 동의가 필요하면 현재 게임웹뷰를 직접 이탈시키지 않고 별도 인앱브라우저에서 인가 코드 요청을 수행합니다.

추가 동의가 필요한 항목 ID 또는 서비스 약관 태그를 확인합니다.
플랫폼에 맞는 인앱브라우저 열기 스킴으로 인가 코드 요청 URL을 엽니다.
scope 또는 service_terms에 필요한 값만 지정합니다.
Redirect URI에서 인가 코드와 state를 검증하고 토큰을 다시 발급합니다.
Redirect URI 페이지가 인앱브라우저 닫기 스킴을 실행해 기존 게임으로 복귀합니다.

플랫폼	열기 스킴	닫기 스킴
iOS	`kakaotalk://inappbrowser?url={AUTHORIZE_URL}`	`kakaotalk://web/close`
Android	`kakaotalk://web/open?url={AUTHORIZE_URL}`	`kakaotalk://web/close`

동의항목 추가 동의는 추가 항목 동의 받기, 서비스 약관 추가 동의는 서비스 약관 선택해 로그인하기의 요청 규격을 따릅니다.

닫기는 두 플랫폼 모두 kakaotalk://web/close 를 사용합니다.
이 스킴은 호출한 웹뷰 자신을 닫으므로, 게임웹뷰 위에 띄운 동의 창에서 호출하면 동의 창만 닫히고 게임웹뷰는 그대로 유지됩니다.
자세한 스킴 규격은 게임웹뷰 SDK의 인앱브라우저 스킴을 참고하세요.

연결 해제

사용자의 파트너사 서비스 탈퇴와 앱 연결 해제는 계정 상태 변경 웹훅 연동으로 처리됩니다.
앱 연결 해제는 카카오가 수행하므로, 파트너사가 연결 해제 API(POST https://kapi.kakao.com/v1/user/unlink)를 직접 호출하는 별도 연동은 필요하지 않습니다.
파트너사는 웹훅으로 전달되는 연결 해제 이벤트를 수신해 회원 정보 삭제와 게임 이용 데이터 파기, 내부 연결 상태 정리를 수행합니다.

파트너사 앱 하나에 여러 게임이 연결되어 있어도 카카오싱크 연결은 파트너사 앱 단위입니다.
연결 해제 시 파트너사의 모든 게임에서 서비스 이용이 해지된다는 점을 사용자에게 안내해야 합니다.

연결 해제 이벤트 수신·검증과 reason별 처리 기준은 계정 상태 변경 웹훅 연동에서 확인하세요.

에러 처리

코드	발생 상황	처리
`access_denied`	사용자가 동의 화면에서 취소	게임을 실행하지 않고 취소 안내를 표시합니다.
`KOE006`	디벨로퍼스에 등록하지 않은 Redirect URI로 인가 코드를 요청	디벨로퍼스에 등록한 값과 요청 값을 일치시킵니다.
`KOE303`	인가 코드 요청과 토큰 요청의 `redirect_uri`가 서로 다름	두 요청에 같은 Redirect URI를 사용합니다.
`KOE237`	토큰 발급 요청 수 제한 초과	즉시 반복 요청하지 않고 공식 문제 해결 가이드를 확인합니다.
`-2`	필수 파라미터 누락 또는 잘못된 값	요청 형식과 앱 설정을 확인합니다.
`-401`	유효하지 않거나 만료된 액세스 토큰	토큰을 갱신하고, 갱신할 수 없으면 인가 코드 요청부터 다시 시작합니다.
`-402`	필요한 동의항목 권한 부족	`required_scopes`를 확인해 추가 동의를 요청합니다.

카카오 API의 -1은 일시적인 내부 장애일 수 있습니다.
이 응답만으로 사용자를 로그아웃하거나 토큰을 즉시 폐기하지 말고 일시 오류로 처리합니다.

운영 적용 전 확인

[ ] 게임 URL 진입 시 로그인 버튼 없이 인가 코드 요청이 시작되는지 확인합니다.
[ ] 인가 코드 요청에 prompt=none이 포함되지 않았는지 확인합니다.
[ ] 앱 미동의 사용자에게 카카오싱크 동의 화면이 표시되는지 확인합니다.
[ ] 동의 완료 사용자가 별도 화면 없이 파트너사 서비스 세션을 발급받는지 확인합니다.
[ ] 인가 코드 콜백에서 state를 검증하는지 확인합니다.
[ ] 카카오 회원번호로 기존 회원과 신규 회원을 정확히 분기하는지 확인합니다.
[ ] 필수 서비스 약관 태그의 동의 상태를 서버에서 검증하는지 확인합니다.
[ ] 새 리프레시 토큰이 응답에 있을 때만 저장 값을 교체하는지 확인합니다.
[ ] 서비스 탈퇴·연결 해제를 계정 상태 변경 웹훅으로 수신해 회원 정보 삭제와 데이터 파기를 처리하는지 확인합니다.

참고 문서

카카오싱크 설정: 비즈 앱·채널·동의항목·서비스 약관 설정
친구 목록 조회 API: 친구 기능의 추가 동의와 친구 정보 조회
계정 상태 변경 웹훅 연동: 연결 해제 이벤트 수신·처리
게임웹뷰 SDK: 인앱브라우저 열기·닫기 스킴
카카오싱크 개발 가이드: 카카오 공식 가입·로그인 구현 흐름
카카오 로그인 REST API: 각 API의 전체 요청·응답 필드와 오류 코드
기술 문의 — 카카오디벨로퍼스 데브톡

카카오싱크 API ​

API 목록 ​

공통 ​

호출 도메인 ​

인증 정보 보관 ​

가입·로그인 처리 순서 ​

인가 코드 요청 ​

Request Query ​

사용자 상태별 동작 ​

Response Query ​

토큰 발급 ​

Request Body ​

Response Body ​

사용자 정보 조회 ​

Request Query ​

Response Body ​

서비스 약관 동의 내역 조회 ​

Request Query ​

Response Body ​

토큰 갱신 ​

Request Body ​

Response Body ​

액세스 토큰 정보 조회 ​

게임 중 추가 동의 ​

연결 해제 ​

에러 처리 ​

운영 적용 전 확인 ​

참고 문서 ​

카카오싱크 API

API 목록

공통

호출 도메인

인증 정보 보관

가입·로그인 처리 순서

인가 코드 요청

Request Query

사용자 상태별 동작

Response Query

토큰 발급

Request Body

Response Body

사용자 정보 조회

Request Query

Response Body

서비스 약관 동의 내역 조회

Request Query

Response Body

토큰 갱신

Request Body

Response Body

액세스 토큰 정보 조회

게임 중 추가 동의

연결 해제

에러 처리

운영 적용 전 확인

참고 문서