페이지 이동경로
  • 문서>
  • 카카오 로그인>
  • JavaScript

카카오 로그인

JavaScript

이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용한 카카오 로그인 구현 방법을 안내합니다.

이 문서에 포함된 기능 일부는 [도구] > [JS 데모]를 통해 사용해 볼 수 있습니다.

카카오 로그인 구현에 필요한 로그인 버튼 이미지는 [도구] > [리소스 다운로드]에서 제공합니다. 해당 로그인 버튼은 디자인 가이드를 참고하여 서비스 UI에 적합한 크기로 수정하여 사용할 수 있습니다.

시작하기 전에

JavaScript SDK 초기화

시작하기를 참고하여 JavaScript SDK를 웹 페이지에 포함하고 초기화한 뒤 카카오 로그인 API를 호출해야 합니다.

카카오 로그인 과정

PC 및 모바일 웹 환경의 서비스는 JavaScript SDK를 사용하면 클라이언트와 서버 요청 각각의 이점을 살려 카카오 로그인을 구현할 수 있습니다. JavaScript SDK의 간편로그인 사용 시, 사용자가 모바일 웹에서 서비스를 이용 중인 경우에는 카카오계정 정보 입력 없이 카카오톡으로 간편하게 로그인할 수 있습니다. 다음은 JavaScript SDK를 사용한 카카오 로그인 과정을 나타낸 시퀀스 다이어그램(Sequence diagram)입니다. 단계별 안내와 REST API를 함께 참고합니다.

카카오 로그인 과정 1. 간편로그인 요청
  1. 서비스 클라이언트에서 사용자가 카카오 로그인 버튼을 누르면 Kakao.Auth.authorize() 함수를 호출해 간편로그인을 요청합니다.
  2. 카카오톡이 카카오 인증 서버에 동의 화면을 요청합니다.
  3. 카카오 인증 서버가 사용자에게 동의 화면을 출력하여 인가를 위한 사용자 동의를 요청합니다.
    • 동의 화면은 서비스 애플리케이션(이하 앱)의 동의항목 설정에 따라 구성됩니다.
  4. 사용자가 필수 동의항목, 이 외 원하는 동의항목에 동의한 뒤 [동의하고 계속하기] 버튼을 누릅니다.
  5. 카카오 인증 서버는 간편로그인 요청 시 지정된 Redirect URI로 인가 코드를 전달합니다.
2. 토큰 받기
  1. 서비스 서버가 Redirect URI로 전달받은 인가 코드로 토큰 받기를 요청합니다.
  2. 카카오 인증 서버가 토큰을 발급해 서비스 서버에 전달합니다.
3. 사용자 로그인 처리
주의

서비스의 사용자 로그인 처리는 서비스에서 자체 구현해야 합니다. 이 문서는 사용자 로그인 처리 구현 시 참고할 수 있는 정보를 제공합니다.

  • 서비스 서버가 발급받은 액세스 토큰으로 사용자 정보 가져오기를 요청해 사용자의 회원번호 및 정보를 조회하여 서비스 회원인지 확인합니다.
  • 서비스 회원 정보 확인 결과에 따라 서비스 로그인 또는 회원 가입 과정을 진행합니다.
  • 이 외 서비스에서 필요한 로그인 절차를 수행한 후, 카카오 로그인한 사용자의 서비스 로그인 처리를 완료합니다.

카카오 로그인

간편로그인

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
Redirect URI 등록
동의항목
OpenID Connect 활성화(선택)
간편가입(선택)
필요 필요:
필수 동의항목
authorize()

카카오 로그인 함수인 Kakao.Auth.authorize()로 간편로그인을 요청합니다. 간편로그인은 카카오계정 ID 및 비밀번호 입력 없이 카카오톡을 통해 사용자를 인증하고 인가 코드를 발급받는 기능입니다.

회원 가입

카카오 로그인은 카카오 플랫폼 안에서 사용자를 인증하고 앱과 연결하는 기능입니다. 카카오는 서비스 데이터에 접근하지 않으므로, 서비스 회원 정보에 회원 가입 처리를 할 수 없습니다. 카카오 로그인 후 필요한 회원 가입 처리나 회원 정보 갱신은 서버에서 인가 코드 및 토큰을 받은 후 구현해야 합니다.

사용자가 카카오 로그인 버튼을 클릭했을 때 Kakao.Auth.authorize()를 호출하면, JavaScript SDK가 간편로그인을 위해 카카오톡을 실행합니다. 카카오톡이 설치되지 않은 환경에서는 카카오계정으로 로그인을 시도하며, 이후 과정은 REST API를 참고합니다.

사용자는 카카오톡의 동의 화면에서 서비스 이용에 필요한 동의항목에 동의하고 로그인하거나 로그인을 취소할 수 있습니다. 카카오 인증 서버는 사용자의 선택에 따라 요청 처리 결과를 담은 쿼리 스트링(Query string)을 redirectUriHTTP 302 리다이렉트(Redirect)합니다. Redirect URI는 [내 애플리케이션] > [카카오 로그인] > [Redirect URI]에 등록된 값 중 하나여야 합니다.

  • 사용자가 모든 필수 동의항목에 동의하고 [동의하고 계속하기] 버튼을 누른 경우
    • redirectUri인가 코드를 담은 쿼리 스트링 전달
  • 사용자가 동의 화면에서 [취소] 버튼을 눌러 로그인을 취소한 경우
    • redirectUri에러 정보를 담은 쿼리 스트링 전달
카카오계정으로 로그인 과정

서비스 서버는 redirectUri로 HTTP 302 리다이렉트된 요청의 Location에서 인가 코드 또는 에러를 확인해 다음과 같이 처리해야 합니다.

  • 간편로그인 요청 성공
    • codestate가 전달된 경우
    • code의 인가 코드 값으로 토큰 받기 요청
  • 간편로그인 요청 실패
    • errorerror_description이 전달된 경우
    • 문제 해결, 응답 코드를 참고해 에러 원인별 상황에 맞는 서비스 페이지나 안내 문구를 사용자에게 보여주도록 처리

REST API에서 보다 자세한 카카오 로그인 과정 안내를 확인할 수 있습니다.

파라미터
이름 타입 설명 필수
redirectUri String 인가 코드를 전달받을 서비스 서버의 URI
[내 애플리케이션] > [카카오 로그인] > [Redirect URI]에서 등록
O
scope String 추가 항목 동의 받기 요청 시 사용
사용자에게 동의 요청할 동의항목 ID 목록
동의항목의 ID는 사용자 정보 또는 [내 애플리케이션] > [카카오 로그인] > [동의항목]에서 확인 가능
쉼표(,)로 구분해 여러 개 전달 가능

주의: OpenID Connect를 사용하는 앱의 경우, scope 파라미터 값에 openid를 반드시 포함해야 함, 미포함 시 ID 토큰이 재발급되지 않음 (참고: scope 파라미터)
X
throughTalk Boolean 간편로그인 사용 여부 (기본값: true) X
prompt String 카카오톡에서 자동 로그인, 기존 로그인 여부와 상관없이 로그인 요청 시 사용
동의 화면 요청 시 추가 상호작용을 요청하고자 할 때 전달하는 파라미터
쉼표(,)로 구분된 문자열 값 목록으로 전달

다음 값 사용 가능:
login: 기존 사용자 인증 여부와 상관없이 사용자에게 카카오계정 로그인 화면을 출력하여 다시 사용자 인증을 수행하고자 할 때 사용, 카카오톡 인앱 브라우저에서는 이 기능이 제공되지 않음
none: 사용자에게 동의 화면과 같은 대화형 UI를 노출하지 않고 인가 코드 발급을 요청할 때 사용, 인가 코드 발급을 위해 사용자의 동작이 필요한 경우 에러 응답 전달
create: 사용자에게 카카오계정 신규 가입 후 로그인하도록 하기 위해 사용, 카카오계정 가입 페이지로 이동 후, 카카오계정 가입 완료 후 동의 화면 출력
select_account: 카카오계정 간편로그인을 요청할 때 사용, 브라우저에 카카오계정 로그인 세션이 있을 경우 자동 로그인 또는 계정 선택 화면 출력

참고: 추가 기능
X
loginHint String 로그인 힌트 주기 요청 시 사용
카카오계정 로그인 페이지의 ID란에 자동 입력할 값

비고: 로그인 힌트 주기 상세 동작 과정 확인 권장
참고: 카카오계정 로그인 시 이메일, 전화번호, 카카오메일 ID를 ID에 입력하여 로그인 가능
X
serviceTerms String 서비스 약관 선택해 동의 받기 요청 시 사용
동의받을 약관 태그 목록
약관 태그는 [내 애플리케이션] > [간편가입]에서 확인 가능
쉼표(,)로 구분된 문자열 값 목록으로 전달
X
state String 카카오 로그인 과정 중 동일한 값을 유지하는 임의의 문자열(정해진 형식 없음)
Cross-Site Request Forgery(CSRF) 공격으로부터 카카오 로그인 요청을 보호하기 위해 사용
각 사용자의 로그인 요청에 대한 state 값은 고유해야 함
인가 코드 요청, 인가 코드 응답, 토큰 발급 요청의 state 값 일치 여부로 요청 및 응답 유효성 확인 가능
X
nonce String OpenID Connect를 통해 ID 토큰을 함께 발급받을 경우, ID 토큰 재생 공격을 방지하기 위해 사용
ID 토큰 유효성 검증 시 대조할 임의의 문자열(정해진 형식 없음)
X

* prompts: Deprecated, 2.3.0 버전부터 prompt로 변경

예제
Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
});

토큰 받기

서비스 서버에서 인가 코드를 사용해 REST API로 토큰 받기를 요청하여 로그인을 완료합니다. OpenID Connect를 사용하는 앱인 경우, 토큰 받기를 통해 ID 토큰을 함께 발급받을 수 있습니다.

  • 토큰은 액세스 토큰(Access token), 리프레시 토큰(Refresh token), ID 토큰(ID token) 세 종류입니다.

카카오 로그인을 완료해 서비스 서버에서 토큰을 발급받으면, 서비스 서버에서 액세스 토큰으로 사용자 정보 가져오기를 호출해 회원 가입 및 로그인에 필요한 사용자 정보를 요청할 수 있습니다. 액세스 토큰을 서비스 클라이언트로 전달해 토큰 할당하면, 서비스 클라이언트에서도 JavaScript SDK를 통한 카카오 API 요청에 사용할 수 있습니다.

주의: 앱 키

JavaScript SDK로 Kakao.Auth.authorize 함수를 호출할 때는 SDK 초기화 시 사용된 JavaScript 키를 사용합니다. 하지만 REST API로 토큰 받기를 요청할 때는 REST API 키를 사용해야 합니다.

토큰 할당하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- - 필요 - setAccessToken()

간편로그인 이외의 카카오 API를 클라이언트에서 JavaScript SDK로 호출하려면 액세스 토큰(Access token) 값을 할당해야 합니다. 카카오 로그인 완료 후 다음과 같이 Kakao.Auth.setAccessToken 함수를 호출해 서비스 서버에서 전달받은 액세스 토큰 값을 JavaScript SDK에서 사용하도록 할당할 수 있습니다.

예제
Kakao.Auth.setAccessToken('${ACCESS_TOKEN}');

추가 기능

간편로그인 요청 시 사용할 수 있는 추가 기능은 다음과 같습니다.

추가 항목 동의 받기

추가 항목 동의 받기는 사용자가 동의하지 않은 동의항목에 대한 추가 동의를 요청할 때 사용하는 추가 기능입니다. Kakao.Auth.authorize() 함수 호출 시 scope 파라미터로 추가 동의받을 항목의 ID 목록을 지정합니다. 응답으로 받은 인가 코드로 토큰 받기를 요청해 카카오 로그인을 완료한 뒤, 이후 카카오 API 요청 시 새로 발급받은 토큰을 사용해야 합니다. 아래는 scope에 이메일, 성별의 추가 동의를 요청하는 예제입니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  scope: 'account_email,gender',
});
주의: OpenID Connect

OpenID Connect를 사용하는 앱의 경우, 추가 항목 동의 받기 요청 시 동의항목 키를 전달하는 scope 파라미터 값에 openid를 반드시 포함해야 합니다. 해당 파라미터 값을 포함하지 않을 경우, ID 토큰이 재발급되지 않습니다. (참고: scope 파라미터)


카카오톡에서 자동 로그인하기

카카오톡에서 자동 로그인은 카카오톡 인앱브라우저를 통한 서비스 페이지 진입 시 서비스 가입 여부에 따른 분기 처리를 지원하는 추가 기능입니다. 이해하기에서 자세한 안내를 확인한 후 사용해야 합니다. 간편로그인 요청 시 prompt 파라미터 값을 none으로 지정합니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  prompt: 'none',
});

서비스 가입을 완료하지 않아 아직 앱과 연결되지 않은 사용자인 경우, 아래와 같이 사용자 동의가 필요하다는 에러 응답이 redirect_uri로 전달됩니다. 이 경우, 사용자가 직접 서비스 페이지를 통해 카카오 로그인 및 서비스 가입을 해야 합니다.

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=consent_required&error_description=user%20consent%20required.

서비스 약관 선택해 동의 받기
카카오싱크 전용

카카오싱크를 도입한 서비스만 사용할 수 있는 기능입니다.

서비스 약관 선택해 동의 받기는 카카오 로그인 동의 화면에 포함할 서비스 약관을 지정하는 추가 기능입니다. 사용자의 서비스 가입 시나리오에 따라 앱에 등록된 서비스 약관 중 특정 서비스 약관을 지정해 동의받고자 할 때 사용합니다. 간편로그인 요청 시 serviceTerms 파라미터로 동의 화면에 포함할 서비스 약관 태그 목록을 지정합니다. 요청 시 [필수 동의]로 설정된 서비스 약관을 하나 이상 포함해야 동의 화면을 출력하고 사용자에게 동의받을 수 있습니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  serviceTerms: 'account_email',
});

OpenID Connect ID 토큰 발급하기

OpenID Connect 사용 서비스인 경우, OpenID Connect 활성화 설정이 되어 있다면 별도 파라미터 없이도 ID 토큰을 함께 발급받을 수 있습니다. OpenID Connect 사용 시 ID 토큰 재생 공격을 방지하기 위해 nonce 파라미터 사용을 권장합니다. 단, 추가 항목 동의 받기 요청 시에는 scope 파라미터에 openid를 포함해야 ID 토큰 재발급이 가능합니다. (참고: scope 파라미터)

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  nonce: '${NONCE}',
});

기존 로그인 여부와 상관없이 로그인하기

기존 로그인 여부와 상관없이 로그인하기는 서비스의 필요에 따라 사용자 인증을 다시 수행하고자 할 때 사용하는 추가 기능입니다. 이 기능을 사용하면 사용자가 브라우저에 카카오계정으로 로그인되어 있는 상태라도 다시 카카오계정으로 로그인하는 과정을 거쳐 서비스에 카카오 로그인하도록 할 수 있습니다. 간편로그인 요청 시 prompt 파라미터 값을 login으로 지정합니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  prompt: 'login',
});

로그인 힌트 주기

인가 코드 받기 요청 시 loginHint 파라미터를 사용하면, 해당 파라미터 값이 ID란에 자동 입력된 카카오계정 로그인 화면을 호출합니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  loginHint: '${HINT}'
});

카카오톡에서 자동 로그인, 로그인 힌트 주기 함께 사용

JavaScript SDK를 사용해 로그인 힌트 주기를 요청할 경우 prompt 파라미터와 함께 사용 가능합니다. 로그인 힌트 주기 상세 동작 과정을 참고합니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  prompt: 'none',
  loginHint: '${HINT}',
});

카카오계정 간편로그인

카카오계정 간편로그인을 사용하려면 prompt 파라미터의 값을 select_account로 지정해 카카오 로그인을 요청합니다.

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  prompt: 'select_account',
});

로그아웃

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
필요 - logout()

현재 로그인한 사용자를 로그아웃 처리합니다.

사용자가 로그아웃 버튼을 눌렀을 때 Kakao.Auth.logout() 함수를 호출하면, 사용자의 액세스 토큰이 만료되어 카카오 API를 호출할 수 없습니다. Kakao.Auth.logout()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

주의

서비스의 로그아웃은 직접 구현해야 합니다. Kakao.Auth.logout() 함수는 로그인 시 발급받은 토큰을 만료시키지만, 카카오계정의 로그아웃이나 서비스의 로그아웃에 영향을 주지 않습니다.

예제
Kakao.Auth.logout()
  .then(function(response) {
    console.log(Kakao.Auth.getAccessToken()); // null
  })
  .catch(function(error) {
    console.log('Not logged in.');
  });

연결 끊기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
필요 - request()

사용자 카카오계정과 앱의 연결을 해제하는 기능입니다.

사용자가 연결 끊기 버튼을 눌렀을 때 url 값을 /v1/user/unlink로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

연결 끊기 후 서비스의 탈퇴 처리

서비스의 탈퇴 처리는 연결 끊기 후 직접 구현해야 합니다. 해당 기능은 사용자와 개발자 웹사이트 앱의 연결을 해제하지만, 서비스 탈퇴에 영향을 주지 않습니다.

파라미터
이름 타입 설명 필수
url String /v1/user/unlink로 고정 O
예제
Kakao.API.request({
  url: '/v1/user/unlink',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

연결 끊기를 직접 호출한 경우가 아닌, 사용자가 서비스와의 연결을 직접 끊었을 때 알림을 받으려면 연결 끊기 알림을 사용합니다.

사용자 정보 가져오기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
동의항목
필요 필요:
사용자 정보를 요청할 모든 동의항목
request()

현재 로그인한 사용자의 카카오계정 정보를 불러옵니다.

property_keys 파라미터를 통해 특정 사용자 정보만 지정해 요청할 수도 있습니다. 해당 파라미터에 사용할 수 있는 키의 종류는 REST API를 참고합니다.

url 값을 /v2/user/me로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v2/user/me 로 고정 O
data Object API에 전달할 파라미터 X
data: 사용자 정보 가져오기
이름 타입 설명 필수
property_keys String[] 요청할 사용자 정보 종류를 지정할 때 사용하는 사용자 정보의 키 목록
사용자 정보 참고
(예: ['kakao_account.email','kakao_account.gender'])
X
예제
Kakao.API.request({
  url: '/v2/user/me',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
예제: 이메일, 성별 정보 가져오기
Kakao.API.request({
  url: '/v2/user/me',
  data: {
    property_keys: ['kakao_account.email', 'kakao_account.gender'],
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

사용자 정보 저장하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
사용자 프로퍼티
필요 - request()

사용자 프로퍼티에 값을 저장합니다.

url 값을 /v1/user/update_profile로 지정하고, [내 애플리케이션] > [사용자 프로퍼티]에 정의한 키 값을 사용해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v1/user/update_profile 로 고정 O
data Object API에 전달할 파라미터 O
data: 사용자 정보 저장하기
이름 타입 설명 필수
properties Object 저장할 사용자 정보, JSON 형식의 키와 값 쌍으로 구성
(예: {'${CUSTOM_PROPERTY_KEY}': '${CUSTOM_PROPERTY_VALUE}'})
O
예제
Kakao.API.request({
  url: '/v1/user/update_profile',
  data: {
    properties: {
      '${CUSTOM_PROPERTY_KEY}': '${CUSTOM_PROPERTY_VALUE}',
    },
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

배송지

배송지 선택하기

권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
필요: 동의항목 플랫폼 등록
카카오 로그인 활성화
동의항목
필요 필요:
배송지 정보(shipping_address)
selectShippingAddress()

사용자가 서비스에 제공할 배송지를 직접 선택할 수 있는 배송지 피커를 불러오고, 선택된 배송지의 ID를 제공합니다.

Kakao.Auth.selectShippingAddress() 함수를 호출합니다. 이 함수는 서비스에 사용자 카카오계정의 전체 배송지 정보를 제공하지 않으며, 사용자가 선택한 특정 배송지의 ID인 addressId를 반환합니다. addressId를 사용해 배송지 가져오기를 요청해 해당 배송지의 정보를 제공받을 수 있습니다.

에러 발생 시 문제 해결에서 원인을 확인합니다.

파라미터

이름 타입 설명 필수
forceMobileLayout Boolean 배송지 피커를 모바일 디바이스에 맞춘 레이아웃으로 고정할 것인지 지정
true: 모바일 레이아웃
false: 반응형 레이아웃
(기본값: false)
X
enableBackButton Boolean 배송지 피커의 뒤로 가기 버튼 노출 여부 지정
true: 뒤로 가기 버튼 노출
false: 뒤로 가기 버튼 비노출
(기본값: true)
X

응답

이름 타입 설명 필수
address_id Number 배송지 ID
returnUrl 파라미터를 사용해 리다이렉트 방식으로 요청한 경우, 쿼리스트링에 포함되어 전달됨
O
status String 사용자의 배송지 선택 완료 여부
success: 사용자가 배송지 선택을 완료한 경우
error: 에러가 발생한 경우
O

예제

// 배송지 선택하기
Kakao.Auth.selectShippingAddress()
  .then(function(selectedAddress) {
    // 배송지 가져오기
    return Kakao.API.request({
      url: '/v1/user/shipping_address',
      data: {
        address_id: selectedAddress.address_id,
      },
    });
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

배송지 가져오기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
필요: 동의항목 플랫폼 등록
카카오 로그인 활성화
동의항목
필요 필요:
배송지 정보(shipping_address)
request()

배송지 ID에 해당하는 특정 배송지 또는 전체 배송지 목록을 제공합니다. 특정 배송지 정보만 요청하려면 data 하위의 address_id 파라미터로 배송지 ID를 지정하여 요청합니다.

url 값을 /v1/user/shipping_address로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 응답 정보는 REST API를 참고합니다.

배송지 선택하기 API를 사용하지 않는 경우, 사용자가 [배송지 정보] 동의항목에 동의하지 않아 배송지를 제공받을 수 없는 경우가 발생할 수 있습니다. 배송지 가져오기 응답에 배송지가 포함되지 않은 경우를 참고합니다.

에러 발생 시 문제 해결에서 원인을 확인합니다.

파라미터
이름 타입 설명 필수
url String /v1/user/shipping_address 로 고정 O
data Object API에 전달할 파라미터 X
data: 배송지 가져오기
이름 타입 설명 필수
address_id Number 배송지 ID
배송지 ID는 배송지 선택하기 또는 배송지 가져오기 응답을 통해 확인 가능
X
from_updated_at Number 배송지 정보가 많아 여러 페이지에 걸쳐 응답이 제공될 때, 기준이 되는 배송지 updated_at 시각
현재 페이지의 마지막 updated_at 시각을 from_updated_at 값으로 전달해 다음 페이지 요청 가능
X
page_size Number 한 페이지에 포함할 배송지 개수(최소값: 2, 기본값: 10) X
예제
Kakao.API.request({
  url: '/v1/user/shipping_address',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
예제: 특정 배송지 정보만 요청
Kakao.API.request({
  url: '/v1/user/shipping_address',
  data: {
    address_id: ${ADDRESS_ID},
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

동의 내역 확인하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
동의항목
필요 - request()

사용자가 동의한 동의항목의 상세 정보를 조회합니다.

앱의 동의항목([내 애플리케이션] > [카카오 로그인] > [동의항목] 에서 설정한 항목)과 사용자가 동의한 동의항목의 상세 정보를 반환합니다. 사용자가 기존에 동의했던 항목은, 현재 앱의 설정과 상관없이 반환 내용에 포함됩니다.

특정 동의항목의 상세 정보만 확인하려면, data 하위의 scopes 파라미터로 동의항목의 ID를 지정하여 요청합니다. 요청 성공 시 지정한 항목의 정보만 반환합니다.

url 값을 /v2/user/scopes로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v2/user/scopes 로 고정 O
data Object API에 전달할 파라미터 X
data: 동의 내역 확인하기
이름 타입 설명 필수
scopes String[] 특정 동의항목에 대한 상세 정보만 불러오려는 경우 사용하는 동의항목의 ID 목록
동의항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의항목] 참고
(예: ['account_email','gender'])
X
예제
Kakao.API.request({
  url: '/v2/user/scopes',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
예제: 이메일, 성별 동의 내역 확인하기
Kakao.API.request({
  url: '/v2/user/scopes',
  data: {
    scopes: ['account_email', 'gender'],
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

동의 철회하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
- 플랫폼 등록
카카오 로그인 활성화
동의항목
필요 - request()

사용자가 동의한 동의항목에 대한 동의를 철회합니다.

동의 내역 확인하기 API를 통해 조회한 동의항목의 상세 정보 중, 동의 철회 가능 여부(revocable) 값이 true인 동의항목만 철회 가능합니다. 철회가 불가능한 항목을 대상으로 요청한 경우 에러를 반환합니다.

url 값을 /v2/user/revoke/scopes로 지정하고, data 하위의 scopes 값에 철회할 동의항목의 ID를 지정하여 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v2/user/revoke/scopes 로 고정 O
data Object API에 전달할 파라미터 O
data: 동의 철회하기
이름 타입 설명 필수
scopes String[] 동의를 철회할 동의항목 ID 목록
동의 내역 확인하기 API 응답에서 동의 철회 가능 여부(revocable) 값이 true인 동의항목만 철회 가능
동의항목 ID는 [내 애플리케이션] > [카카오 로그인] > [동의항목] 참고
(예: ['account_email','gender'])
O
예제
Kakao.API.request({
  url: '/v2/user/revoke/scopes',
  data: {
    scopes: ['account_email', 'gender'],
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

서비스 약관 동의 내역 확인하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
필요: 카카오싱크 플랫폼 등록
카카오 로그인 활성화
동의항목
간편가입
필요 - request()

카카오싱크 전용

카카오싱크를 도입한 서비스만 사용할 수 있는 기능입니다.

사용자가 어떤 서비스 약관에 동의하고 로그인했는지 확인합니다.

앱에 설정된 전체 서비스 약관 목록을 조회하려면 resultapp_service_terms로 지정해 요청합니다. 특정 서비스 약관만 조회하려면 tags에 해당 서비스 약관의 태그(Tag)를 지정해 요청합니다.

url 값을 /v2/user/service_terms로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v2/user/service_terms 로 고정 O
data Object API에 전달할 파라미터 X
data: 서비스 약관 동의 내역 확인하기
이름 타입 설명 필수
result String 조회할 서비스 약관 목록, 다음 중 하나
agreed_service_terms: 사용자가 동의한 서비스 약관 목록(기본값)
app_service_terms: 앱에 사용 설정된 서비스 약관 목록
X
tags String 조회할 서비스 약관 태그, result로 지정한 목록 내 서비스 약관으로 한정
여러 태그를 쉼표(,)로 구분한 하나의 문자열로 전달
X
예제: 사용자가 동의한 서비스 약관 조회
Kakao.API.request({
  url: '/v2/user/service_terms',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
예제: 앱에 사용 설정된 서비스 약관 목록 조회
Kakao.API.request({
  url: '/v2/user/service_terms',
  data: {
    result: 'app_service_terms',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
예제: 특정 태그의 서비스 약관만 조회
Kakao.API.request({
  url: '/v2/user/service_terms',
  data: {
    tags: 'test_tag1,test_tag2'
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

서비스 약관 동의 철회하기

기본 정보
권한 사전 설정 카카오 로그인 사용자 동의 레퍼런스
필요: 카카오싱크 플랫폼 등록
카카오 로그인 활성화
동의항목
간편가입
필요 - request()

카카오싱크 전용

카카오싱크를 도입한 서비스만 사용할 수 있는 기능입니다.

사용자가 동의한 서비스 약관의 동의를 철회합니다. 사용자 약관 동의 내역 확인하기 응답의 동의 철회 가능 여부(revocable) 값이 true인 서비스 약관만 철회 가능합니다.

url 값을 /v2/user/revoke/service_terms로 지정해 Kakao.API.request() 함수를 호출합니다. tags에 동의 철회할 서비스 약관의 태그(Tag)를 문자열 리스트(List of Strings)로 전달해야 합니다.

Kakao.API.request()Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터
이름 타입 설명 필수
url String /v2/user/revoke/service_terms 로 고정 O
data Object API에 전달할 파라미터 O
data: 서비스 약관 동의 철회하기
이름 타입 설명 필수
tags String 동의 철회할 서비스 약관 태그
여러 태그를 쉼표(,)로 구분한 하나의 문자열로 전달

비고: 서비스 약관 동의 내역 확인하기 API 응답에서 동의 철회 가능 여부(revocable) 값이 true인 서비스 약관만 철회 가능
O
예제
Kakao.API.request({
  url: '/v2/user/revoke/service_terms',
  data: {
    tags: 'test_tag1,test_tag2'
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Legacy

카카오 로그인의 Legacy Kakao SDK for JavaScript(이하 Legacy JavaScript SDK) 개발 가이드는 다음 링크에서 확인할 수 있습니다. 추후 Legacy JavaScript SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 JavaScript SDK로 변경할 것을 권장합니다.

더 보기