사용자 관리

사용자 관리는 카카오 플랫폼 서비스에서 제공하는 핵심 기능 중 하나입니다. 사용자 관리는 쉽고 빠른 방법으로 사용자의 계정을 카카오 플랫폼과 연결해줍니다. 해당 기능을 통하여 안전하고 보다 더 강력한 참여형 사용환경의 앱을 만들 수 있습니다.

사용자 관리의 상세 기능은 다음과 같습니다.

  • 로그인
    카카오계정을 통한 빠르고 간편한 로그인 기능을 지원합니다.
  • 로그아웃
    로그인된 사용자의 세션 연결을 해제합니다.
  • 앱 연결
    로그인한 사용자와 앱을 카카오 플랫폼에 연결합니다. 사용자가 앱 가입/등록 요청을 하는 경우와 비슷합니다.
  • 앱 연결 해제
    카카오 플랫폼에 연결된 사용자와 앱의 연결을 영구 해제합니다. 사용자가 앱 탈퇴 요청을 하는 경우와 비슷합니다.
  • 사용자 정보 요청
    사용자에 대한 정보를 얻어 올 수 있습니다. 해당 기능을 사용하기 위해서는 로그인 및 앱 연결이 되어 있어야 합니다.
  • 사용자 정보 저장
    사용자에 대한 특정 정보를 저장할 수 있습니다. 해당 기능을 사용하기 위해서는 로그인 및 앱 연결이 되어 있어야 합니다.
  • 사용자 ID 리스트 요청
    앱 사용자들의 리스트를 얻어 올 수 있습니다. 해당 기능은 어드민 키(Admin Key)를 이용해 호출해야 합니다.
  • 사용자 토큰 유효성 검사 및 정보 얻기
    로그인을 통해 얻은 사용자 토큰(Access Token)의 유효성을 검사하거나 부가 정보를 얻을 수 있습니다.
  • 동적동의
    API 사용 시 사용자의 추가 동의가 필요한 경우 동적동의 과정이 필요합니다.

    로그인 API를 사용할 때 필요한 버튼은 여기를 참조하세요.

로그인

카카오계정을 이용하여 빠르고 간편하게 로그인을 할 수 있습니다.

해당 로그인 기능은 OAuth 2.0을 지원합니다. 다음은 카카오 플랫폼 서비스에서 제공하는 가장 일반적인 OAuth 인증의 과정입니다.

  1. 사용자는 카카오계정으로 로그인 버튼을 클릭합니다.
  2. 카카오톡 앱에 연결된 카카오계정의 자격정보(Credentials)를 통해 사용자를 인식합니다.
  3. 자격정보가 올바르다면 사용자(Resource Owner)로부터 접근 자원에 대한 동의/허가를 얻습니다.
  4. 위 3까지 성공적으로 수행되었다면 인증 코드(Authorization Code)가 발급됩니다. 해당 인증 코드는 Redirection URI를 기반으로 Third 앱에 전달됩니다.
  5. Third 앱에서는 전달받은 인증 코드를 기반으로 사용자 토큰(Access Token, Refresh Token)을 요청하고 얻게 됩니다.

    사용자 토큰은 카카오 플랫폼 서비스에서 제공하는 로그인 기반의 기능을 사용하는데 있어 중요한 키로 사용됩니다. OAuth 2.0의 보다 자세한 내용은 여기를 참고하세요.

코드 받기

로그인 버튼 클릭시 먼저 사용자 동의를 거쳐 토큰을 발급 받을 수 있는 코드를 받아와야 합니다.

카카오계정으로 로그인을 위한 버튼의 다양한 이미지는 여기에서 다운로드 할 수 있습니다.

[Request]

GET /oauth/authorize?client_id={app_key}&redirect_uri={redirect_uri}&response_type=code HTTP/1.1
Host: kauth.kakao.com
설명 필수
client_id 앱 생성시 발급 받은 REST API 키. O
redirect_uri 코드를 리다이렉트 해줄 URI.
설정 > 일반 > > 사이트 도메인 에서 설정한 각각의 도메인에 설정 > 일반 > > Redirect Path 를 붙인 URI.
O
response_type code 문자열 값으로 고정. O
state Cross-site Request Forgery 공격을 보호하기 위한 임의의 고유한 문자열. 리다이렉트시 해당 값이 전달됨. X
encode_state state가 encode되어 있는지에 대한 유무(boolean). true(y 또는 1)일 경우 state 전달시 decoded state로 전달. false(n 또는 0)일 경우 별도의 decode를 하지 않고 state를 그대로 전달. default false. X

redirect_uri의 예는 다음과 같습니다. 예를 들어, 사이트 도메인으로 http://your.website.domain.com을, Redirect Path로 "/kakao_oauth"를 설정하였다면 redirect_uri는 http://your.website.domain.com/kakao_oauth 형식이 됩니다. Redirect Path의 기본값은 "/oauth" 입니다.

해당 기기에서 카카오계정으로 로그인이 된 적이 없다면 로그인 창으로 리다이렉트 됩니다. 한번 로그인한 카카오계정은 6시간 동안 유효함으로 6시간 이내에 로그인 한 적이 있다면 바로 접근 자원에 대한 동의/허가를 위한 화면이 나타납니다.

[Response]

허용을 클릭하면 코드를 쿼리 스트링으로 담아 redirect_uri로 리다이렉트 합니다. redirect_uri 요청에 대해 처리하여 code를 얻도록 합니다.

HTTP/1.1 302 Found
Content-Length: 0
Location: {redirect_uri}?code={authorize_code}

사용자 토큰 받기

코드를 얻은 다음, 이를 이용하여 실제로 API를 호출할 수 있는 사용자 토큰(Access Token, Refresh Token)을 받아 올 수 있습니다.

[Request]

POST /oauth/token HTTP/1.1
Host: kauth.kakao.com

아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
grant_type authorization_code로 고정 O
client_id 앱 생성시 발급 받은 REST API 키. O
redirect_uri 코드가 리다이렉트 된 URI.
설정 > 일반 > > 사이트 도메인에서 설정한 각각의 도메인에 설정 > 일반 > > Redirect Path 를 붙인 URI.
O
code 코드 받기에서 발급 받은 인증된 코드. O
client_secret 설정 > 일반 > Client Secret 에서 생성한 client_secret 코드
ACTIVE 상태 인 경우 필수로 설정해야 함
X

예를들어 다음과 같이 POST로 요청합니다.

curl -v -X POST https://kauth.kakao.com/oauth/token \
 -d 'grant_type=authorization_code' \
 -d 'client_id={app_key}' \
 -d 'redirect_uri={redirect_uri}' \
 -d 'code={authorize_code}'

[Response]

응답 바디는 JSON 객체로 아래 값을 포함합니다.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type":"bearer",
    "refresh_token":"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "expires_in":43199,
    "scope":"Basic_Profile"
}

요청 결과로 API를 호출할 때 사용하는 access_token과 해당 토큰의 만료 시간(초 단위), 또한 토큰을 갱신 할 수 있는 refresh_token을 받습니다.

사용자 토큰 갱신

토큰이 만료되면, 토큰 요청 응답으로 받은 또는 토큰 갱신 요청 응답으로 받은 refresh_token을 이용하여 토큰을 갱신합니다.

access_token은 발급 받은 후 12시간-24시간(정책에 따라 변동 가능)동안 유효합니다. refresh token은 한달간 유효하며, refresh token 만료가 1주일 이내로 남은 시점에서 사용자 토큰 갱신 요청을 하면 갱신된 access token과 갱신된 refresh token이 함께 반환됩니다.

토큰을 갱신하기 위해서는 아래 요청이 필요합니다.

[Request]

POST /oauth/token HTTP/1.1
Host: kauth.kakao.com

아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
grant_type refresh_token로 고정 O
client_id 앱 생성시 발급 받은 REST API 키. O
refresh_token 토큰 발급시 응답으로 받은 refresh_token으로 Access Token을 갱신하기 위해 사용된다. O
client_secret 설정 > 일반 > Client Secret 에서 생성한 client_secret 코드
ACTIVE 상태 인 경우 필수로 설정해야 함
X

예를들어 다음과 같이 POST로 요청합니다.

curl -v -X POST https://kauth.kakao.com/oauth/token \
 -d 'grant_type=refresh_token' \
 -d 'client_id={app_key}' \
 -d 'refresh_token={refresh_token}'

[Response]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww",
    "token_type":"bearer",
    "refresh_token":"zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",  //optional
    "expires_in":43199,
}

요청 결과로 갱신된 새로운 access_token과 해당 토큰의 만료 시간, 또한 Refresh Token 자체가 갱신되었으면 갱신된 refresh_token도 함께 받게 됩니다. refresh_token은 응답에 포함될 수도 있고 포함되지 않을 수도 있기 때문에 포함된 경우에 대해서만 갱신하여 저장하도록 합니다.

로그아웃

카카오계정과의 세션 연결을 해제하는 기능입니다.

로그인 기능은 멀티디바이스를 지원합니다. 만약 사용자가 여러 기기에서 하나의 같은 카카오계정으로 로그인 후 로그아웃을 수행한다면, 해당 로그아웃을 수행한 기기에서만 세션 연결이 해제됩니다.

[Request]

POST /v1/user/logout HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

사용자 토큰을 헤더에 담아 POST로 요청합니다. 예를 들면,

curl -v -X POST https://kapi.kakao.com/v1/user/logout \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

응답 바디는 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 로그아웃된 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

앱 연결

앱 연결은 로그인한 사용자와 앱을 카카오 플랫폼에 연결함으로서 일반적으로 사용자가 앱 가입/등록 요청을 하는 경우와 비슷합니다. 카카오 플랫폼 서비스를 올바로 사용하기 위해서는 로그인 후 반드시 앱 연결이 선행되어야 하며, 최초 한번만 수행가능합니다. 앱 연결이 올바로 수행되면 해당 사용자에 대한 고유한 아이디(ID)가 부여됩니다.

로그인 수행 후, 사용자 정보를 호출하였으나 가입이 안된 상태라 실패한다면 가입 창을 띄워줘야 합니다. 가입 시 개별 사용자에 대한 특정 부가정보를 저장하고 싶은 경우 가입과 함께 사용자 정보를 저장할 수 있습니다. 이는 가입 후에 사용자 정보 저장을 통해 업데이트 될 수 있습니다.

[Request]

POST /v1/user/signup HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded;charset=utf-8

사용자 토큰을 헤더에 담아 POST로 요청합니다. 앱 연결과 동시에 사용자 정보를 저장하고 싶은 경우, 사용자 토큰과 함께 아래 파라미터의 값들을 POST로 요청할 수 있습니다. 사용자 정보는 가입 후 사용자 정보 저장을 통해 업데이트 될 수 있습니다.

설명 필수
properties 가입하는 사용자의 정보. JSON 형태의 key-value. X

예를 들어, 가입시 사용자의 나이와 성별을 받고자 한다면 아래와 같이 요청합니다.

age와 gender는 사용자 관리 설정에서 커스텀 사용자 정보 컬럼으로 추가되어 있어야 합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/signup \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'properties={"age":"23", "gender":"female"}'

[Response]

앱 연결 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 앱연결된 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

앱 연결 해제

앱 연결 해제는 카카오 플랫폼에 연결된 사용자와 앱의 연결을 영구 해제함으로서 일반적으로 사용자가 앱 탈퇴 요청을 하는 경우와 비슷합니다. 앱 연결 해제가 수행된 사용자는 영구적으로 복구가 불가능하며 카카오 플랫폼 서비스를 더이상 사용할 수 없습니다. 단, 다시 앱 연결을 통해 새로운 데이타로 카카오 플랫폼 서비스를 이용할 수는 있습니다.

앱 연결 해제를 수행할 경우 카카오 플랫폼에서 관리하는 해당 사용자의 데이타는 모두 지워집니다. 단, Third앱에서 저장하는 데이타의 경우 카카오 플랫폼 서비스에서는 책임을 질 수 없습니다. 이는 Third앱에서 지워야 할 의무를 가집니다(보다 자세한 내용은 정책 및 약관을 참고하세요). 이것이 흔히 말하는 앱 탈퇴와 앱 연결 해제와의 차이점입니다.

[Request]

POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}

어드민 키(Admin Key)는 절대로 유출되어서는 안 되는, 일종의 마스터 키(Master Key)이므로 반드시 Third 서버에서 API를 호출해야 합니다. 어드민 키는 카카오 웹사이트의 내 애플리케이션에서 확인할 수 있습니다. 만약 iOS, Android 애플리케이션의 소스코드 내에서 어드민 키를 사용할 경우, 해당 애플리케이션은 보안에 취약할 수 있습니다.

사용자 토큰/어드민키를 헤더에 담아 POST로 요청합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/unlink \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl -v -X POST https://kapi.kakao.com/v1/user/unlink \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'target_id_type=user_id&target_id=123456789'

[Response]

앱 연결 해제 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 앱 연결 해제된 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

사용자 정보 요청

사용자 정보 요청은 사용자에 대한 아이디(ID) 와 카카오계정 이메일(email) 및 개별 상세 정보를 얻어 올 수 있는 기능입니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 또한 앱 연결이 전제가 되어 있어야 합니다.

사용자 아이디(ID)의 경우 앱 연결 과정에서 발급하는 앱별 사용자의 고유 아이디입니다. 해당 아이디를 통해 사용자를 앱에서 식별 가능하며, 앱 연결 해제를 하지 않는 한 같은 사용자는 같은 값으로 계속 유지됩니다.

카카오계정 이메일을 수집하여 사용할때 다음 내용을 주의하세요.

  • 서비스에 제공되는 사용자의 카카오계정 이메일은 인증 받지 않은 이메일도 포합됩니다. 사용자 정보 요청시 이메일과 이메일 인증여부도 포함되어 있으니, 서비스에서는 이메일을 활용하기 전에 이메일 인증여부를 항상 확인해야 합니다.

    서비스 가입시 사용자의 이메일 정보가 필요하다면, 서비스에서 사용자에게 카카오계정 이메일이 인증받지 않았음을 안내하고 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다.(예. 인증받지 않은 카카오계정을 사용중입니다. 이메일주소 입력이 필요합니다.)

  • 사용자가 카카오계정의 이메일 제공을 거부한 경우 사용자의 이메일은 제공되지 않습니다. 서비스 가입시 사용자의 이메일 정보가 필요하다면, 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다.

  • 카카오계정의 이메일은 사용자의 요청으로 인해 변경 될 수 있습니다. 서비스에서는 이메일을 활용하는 시점에 이메일의 변경 유무를 확인할 것을 권장합니다.

관리자가 특정 사용자의 정보를 얻어내고자 할 때는 어드민 키와 사용자 ID를 통해서도 요청할 수 있습니다.

해당 기능을 사용하기 위해서는 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

GET/POST /v1/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8
GET/POST /v1/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
Content-type: application/x-www-form-urlencoded;charset=utf-8

어드민 키(Admin Key)는 절대로 유출되어서는 안 되는, 일종의 마스터 키(Master Key)이므로 반드시 Third 서버에서 API를 호출해야 합니다. 어드민 키는 카카오 웹사이트의 내 애플리케이션에서 확인할 수 있습니다. 만약 iOS, Android 애플리케이션의 소스코드 내에서 어드민 키를 사용할 경우, 해당 애플리케이션은 보안에 취약할 수 있습니다.

어드민 키와 사용자 아이디(ID)를 인증정보로 사용할 경우 아래 파라미터와 함께 요청합니다.

설명 필수
target_id_type 사용자 아이디의 타입. user_id로 고정된 값 O
target_id 사용자 아이디(ID) O

사용자 토큰 또는 어드민키와 사용자 아이디(ID)를 헤더에 담아 GET/POST로 요청합니다. 사용자 인증정보와 함께 아래 파라미터의 값을 선택적으로 추가할 수 있습니다.

설명 필수
propertyKeys 사용자 정보의 키 리스트. JSON Array 형태. X
secure_resource 이미지 url을 https로 반환할지 여부. true/false X

예를 들어 사용자 전체 정보를 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X GET https://kapi.kakao.com/v1/user/me \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

예를 들어 사용자 정보 중 이름과 나이만 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/me \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d 'propertyKeys=["name","age"]'

해당 앱의 서버에서 사용자 아이디(ID)가 12345인 사용자의 이름과 나이만 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/me \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'target_id_type=user_id&target_id=12345' \
  -d 'propertyKeys=["name","age"]'

[Response]

사용자 정보 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 유저의 고유 ID signed int64
kaccount_email 사용자 카카오계정의 이메일 String
kaccount_email_verified 인증받은 카카오계정 이메일인지 여부
인증받지 않은 이메일은 변경될 수 있습니다.
Boolean
properties 사용자의 정보. Json 형태의 key-value.
사용자 정보 키를 지정한 경우는 해당 키에 대한 정보만 포함 합니다.
String

기본으로 제공되는 사용자 프로퍼티로는 nickname, profile_image, thumbnail_image가 있습니다.

  • nickname: 카카오톡 또는 카카오스토리의 닉네임 정보
  • profile_image: 640px * 640px 크기의 카카오톡 또는 카카오스토리의 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 480px * 480px ~ 1024px * 1024px 크기를 가질 수 있음)
  • thumbnail_image: 110px * 110px 크기의 카카오톡 또는 카카오스토리의 썸네일 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 160px * 213px 크기를 가질 수 있음)
HTTP/1.1 200 OK
{
    "id":123456789,
    "kaccount_email": "xxxxxxx@xxxxx.com",
    "kaccount_email_verified": true,
    "properties":
    {
        "nickname":"홍길동",
        "thumbnail_image":"http://xxx.kakao.co.kr/.../aaa.jpg",
        "profile_image":"http://xxx.kakao.co.kr/.../bbb.jpg",
        "custom_field1":"23",
        "custom_field2":"여"
        ...
    }
}
HTTP/1.1 200 OK
{
    "id":123456789,
    "kaccount_email": "xxxxxxx@xxxxx.com",
    "kaccount_email_verified": true,
    "properties":
    {
        "nickname":"홍길동",
        "custom_field1":"23"
        ...
    }
}

추가적으로 사용자의 카카오계정 이메일을 수집하고 싶은 경우, 에러가 발생한다면 아래 가이드를 참고하세요.

이메일 항목에 동의 없이 가입한 사용자의 카카오계정 이메일을 수집하기 위해서는 사용자의 동적동의가 필요합니다. 이메일이 필요한 시점에 사용자의 동적동의를 받을 수 있습니다.

사용자의 동적동의가 필요한 경우에는 다음과 같이 사용자의 카카오계정 이메일 정보를 요청해야하고, 동적동의에서 가이드하는 내용과 같이 에러를 처리해 사용자에게 동의를 받아야 합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/me \
-H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d 'property_keys={"kaccount_email"}'
HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "USER_ME",
  "required_scopes": [
    "kaccount_email"
  ],
  "allowed_scopes": [
    "profile"
  ]
}

아래는 이메일을 사용하겠다고 설정하지 않은 경우에 발생할 수 있는 에러 응답입니다.

아래와 같은 에러가 발생하는 경우에는, 설정 > 사용자 관리 > 동의항목 관리 에서 이메일을 사용하겠다고 설정해야 합니다.

HTTP/1.1 403 Forbidden
{
  "msg": "[맛있는 앱] App disabled [account_email] scopes for [USER_ME] API on developers.kakao.com. Enable it first.",
  "code": -3
}

사용자 정보 저장

사용자 정보 저장은 개별 사용자에 대한 특정 부가정보를 저장할 수 있는 기능입니다. 카카오 플랫폼 서비스에서 제공하는 기본 부가정보 외에도, 개발자 웹사이트를 통해 앱별 커스텀한 정보를 선언하여 유저별 데이타를 저장할 수 있습니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 또한 앱 연결이 전제가 되어 있어야 합니다.

사용자 정보 저장 기능으로 수정할 수 없는 사용자의 정보도 존재합니다. 예를 들어 사용자의 아이디(ID)는 수정될 수 없습니다.

profile_image와 thumbnail_image 둘 중 하나만 저장 요청하여도 640px * 640px, 110px * 110px 크기로 각각 저장됩니다. 두 이미지를 함께 저장 요청한 경우 profile_image를 원본으로 각 크기로 저장됩니다.

[Request]

POST /v1/user/update_profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8

사용자 토큰과 함께 아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
properties 가입하는 사용자의 정보. JSON 형태의 key:value. O

예를 들어, 사용자 정보에 기본 부가정보 중 nickname과 커스텀 정보 age을 갱신하고자 한다면 아래와 같이 요청합니다.

age와 gender는 사용자 관리 설정에서 커스텀 사용자 정보 컬럼으로 추가되어 있어야 합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/update_profile \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'properties={"nickname":"홍길동","age":"22"}'

[Response]

사용자 정보 저장 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

사용자 리스트 요청

해당 앱의 유저 ID 리스트를 페이징 형식으로 가져옵니다. 페이징은 전체 리스트를 여러번의 API 요청으로 분리하여 제공하는 방식입니다. 먼저 아무런 파라미터 값 없이 요청을 보내면, 유저 ID의 오름차순으로 1 ~ 100 번째 유저 ID 리스트 페이지가 나옵니다. 또한 결과값과 함께, 이전 페이지 URL과 다음 페이지 URL 이 포함되어있는데, 이전 페이지 URL 은 현재 페이지 전에 나와야 할 페이지 (현재 페이지에서 가장 작은 유저 ID보다 유저 ID가 작은 100명의 페이지)의 URL이고 다음 페이지 URL 은 현재 페이지 다음에 나와야 할 페이지 (현재 페이지에서 가장 큰 유저 ID보다 유저 ID가 큰 100명의 페이지)의 URL입니다. 만약 이전 페이지나 다음 페이지에 들어갈 유저가 없다면, URL에 null값이 리턴됩니다.

따라서, 전체 유저를 모두 얻고 싶다면 아래와 같은 단계로 진행하면 됩니다.

  1. 아무런 파라미터 값이 없는 요청을 한번 보냅니다.
  2. 받아온 결과에서 사용자자 ID들을 처리하고, 다음페이지 URL을 요청합니다.
  3. 2를 반복하다가 URL이 null이 리턴된 경우, 더이상 받아올 사용자가 없으므로 멈춥니다.

특수한 방식의 요청을 하고 싶으신 경우에는 아래의 from_id, limit, order를 이용해 'from_id보다 유저 ID가 큰/작은 순서로 limit명의 앱 유저 리스트'를 만들어 낼 수 있습니다.

해당 기능을 사용하기 위해서는 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

GET /v1/user/ids HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
Content-type: application/x-www-form-urlencoded;charset=utf-8

어드민 키와 함께 아래 파라미터 값을 요청할 수 있습니다.

설명 필수
limit 페이지에 들어갈 최대 사용자 수. (최소 1명, 최대 100, 기본값 100) Integer 형태. X
from_id 페이징을 시작하는 기준이되는 유저 ID 값. 일반적으로 Response에서 나온 결과를 이용합니다. 값이 없을 경우 가장 작은 ID를 가진 유저부터 읽어옵니다. Long 형태 X
order 페이징을 검색하는 방향. asc / desc 중 하나 (기본값 asc) X

예를 들어, 첫 사용자 100명의 전체 정보를 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X GET https://kapi.kakao.com/v1/user/ids \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

유저 ID가 12345보다 큰 사용자 3명만 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/ids \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'limit=3&order=asc' \
  -d 'from_id=12345'

[Response]

사용자 정보 리스트트 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
elements 유저들의 ID 리스트. List
total_count 앱의 총 사용자 수. Integer
before_url 이전 페이지 URL. 이전 페이지가 없을 경우 null. String
after_url 다음 페이지 URL. 다음 페이지가 없을 경우 null. String
HTTP/1.1 200 OK
{
  "elements": [
  1376016924426111111, 1376016924426222222, 1376016924426333333 ]
  , "total_count": 9
  , "before_url": "http://kapi.kakao.com/v1/user/ids?limit=3&order=desc&from_id=1376016924426111111&app_key=12345674ae6e12379d5921f4417b399e7"
  , "after_url": "http://kapi.kakao.com/v1/user/ids?limit=3&order=asc&from_id=1376016924426333333&app_key=12345674ae6e12379d5921f4417b399e7"
}

사용자 토큰 유효성 검사 및 정보 얻기

사용자 토큰 받기를 통해 얻은 Access Token의 유효성을 검사하거나 해당 토큰의 부가 정보를 얻습니다.

사용자 토큰 갱신을 위해서는 현재 가지고 있는 토큰이 만료 되었는지, 얼마동안 유효한지 등을 특정 주기안에서 호출해야 할 필요성이 있습니다.

사용자 토큰의 경우 Native SDK, REST API, Javascript SDK등을 통해 얻을 수 있습니다. 어느 플랫폼에서 얻은 사용자 토큰이든 관계없이, 로그인 후 얻은 사용자 토큰으로 주어진 기능을 사용할 수 있습니다.

[Request]

GET /v1/user/access_token_info HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8

사용자 토큰을 요청 헤더에 담아 GET Method로 요청합니다. 다른 추가적인 파라미터는 필요없습니다.

다음은 해당 기능의 요청 예제입니다.

curl -v -X GET https://kapi.kakao.com/v1/user/access_token_info \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 사용자 ID signed int64
expiresInMillis 주어진 토큰의 남은 유효기간(Milli-seconds). 0 또는 양수 signed int64
appId 주어진 토큰을 발급한 앱의 id signed int64
HTTP/1.1 200 OK
{
    "id":123456789,
    "expiresInMillis":239036,
    "appId":1234
}

위의 응답은 주어진 토큰이 올바를 경우에 대한 예제입니다. 만약 주어진 사용자 토큰이 잘못된 형식일 경우 HTTP Status 400에 code -2가 반환될 수 있으며, 이미 토큰이 만료되었을 경우 HTTP Status 401에 code -401이 반환될 수 있습니다.

응답 에러 코드가 -401일 경우(보통 토큰 만료일 경우), 일반적으로 호출한 곳에서 사용자 토큰 갱신을 해 주어야 합니다. 응답 에러 코드가 -1일 경우 카카오 플랫폼 서비스의 일시적 내부 장애 상태이므로, 토큰을 강제 만료(폐기) 또는 로그아웃 처리를 하지 않는 것이 좋습니다(일시 장애 메시지 처리를 권장합니다). 그 외의 에러는 앱/사용자/토큰 등의 상태가 더이상 유효하지 않는 경우이므로, 토큰 재갱신을 하여도 큰 의미는 없습니다. 이 경우는 로그아웃 처리를 권장합니다.

자세한 에러에 대한 정보는 에러 코드를 참고하세요.

동적동의

API 사용 시 사용자의 추가 동의가 필요한 경우 동적동의 과정이 필요합니다.

예를 들어 카카오톡 메시지 전송에 대한 동의를 하지않은 사용자가 나에게 보내기 요청합니다.

curl -v -X POST 'https://kapi.kakao.com/v2/api/talk/memo/default/send' \
-H 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'template_object={...}'

[Response]

요청이 실패하면서 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명
required_scopes 현재 API를 사용하기 위해서 필요한 동의항목
allowed_scopes 사용자가 동의한 동의항목
HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

API 응답의 required_scopes를 포함해서 동적동의를 요청해야 합니다.

[Request]

GET /oauth/authorize?client_id={app_key}&redirect_uri={redirect_uri}&response_type=code&scope={required_scopes.join(',')} HTTP/1.1
Host: kauth.kakao.com
설명 필수
scope API 요청 시 응답으로 받은 required_scopes
","로 합쳐서 전달합니다.
O

동적동의 과정은 코드 받기 과정과 동일합니다. 코드 받기을 참고해 주세요.


Last Modified : 2017-08-22