Kakao API

2025-latest · active · verified Sat Feb 28

Kakao REST API provides access to Kakao Login, KakaoTalk messaging, friends list, maps, and AI features. Primary documentation is in Korean. English docs exist but are incomplete and lag behind Korean versions. No official Python/Node package — all integrations use REST API directly with app keys.

Warnings

breaking Client secret is now enabled by default for all new REST API keys. Omitting client_secret in token requests causes KOE101 error.
Fix: Include client_secret parameter in all Get token API calls, or disable Client secret in app settings
breaking Access tokens expire in 6 hours. Refresh tokens expire in 60 days (extendable to 2 months). Expired access token returns error code -401.
Fix: Implement token refresh using refresh_token before expiry. Check error code -401 and refresh proactively.
gotcha Error codes are negative integers with no consistent pattern. code:-401 can mean token expired, token not found, or app key deactivated — check msg field for the actual cause.
Fix: Always read the msg field in error responses, not just the code
gotcha Primary documentation is in Korean at developers.kakao.com. English docs exist but are incomplete and often lag Korean versions by weeks.
Fix: For complete specs use Korean docs at developers.kakao.com/docs/latest/ko/ — use translation tools if needed
gotcha Token issuance rate limit returns KOE237 error. Not documented clearly in English docs.
Fix: Implement exponential backoff on KOE237. Check Korean troubleshooting docs for current limits.
gotcha Scope/consent items must be pre-configured in Kakao Developers app settings before requesting. Missing scope returns -402 insufficient scopes error.
Fix: Configure all required consent items in app settings at developers.kakao.com before going to production
gotcha Admin key has full permissions and must never be exposed client-side. Reissuing app keys is irreversible — all existing keys stop working immediately.
Fix: Use Admin key only in server-side code. Store in environment variables only.

Install

pip install requests Python (no official SDK — use requests)
npm install axios Node.js (no official SDK — use axios or fetch)

Imports

Authorization header
```
Authorization: KakaoAK {REST_API_KEY}
```
Kakao uses KakaoAK prefix for app-level auth, not Bearer. Bearer is only for user access tokens.
User token auth
```
Authorization: Bearer {ACCESS_TOKEN}
```
Use Bearer only when authenticating as a user with an access token from OAuth flow.

Quickstart

Retrieve Kakao user info using a valid access token.

import requests

# Get user info with access token
headers = {
    'Authorization': f'Bearer {ACCESS_TOKEN}'
}
response = requests.get(
    'https://kapi.kakao.com/v2/user/me',
    headers=headers
)
print(response.json())

view raw JSON →