kakao developers

iOS

This document describes how to integrate Kakao Login APIs into your service with the Kakao SDK for iOS.

To learn about each API in detail, refer to Understand concepts.

For a Kakao Login button, you can download the resources that Kakao provides or customize it according to your service UI by referring to the Design guide.

Kakao Login button resource downloadoutlinkDesign guide

Before you begin

Before using Kakao Login APIs with the iOS SDK,

1. Register the iOS platform.
2. Add modules.
3. (Optional) Configure for Login with Kakao Talk.

Add modules

To implement Kakao Login, you need to install both the Kakao Login and Authentication modules. After adding KakaoSDKAuth (Authentication and token management module) and KakaoSDKUser (Kakao Login module) to the Podfile, add the import statement for the modules as follows.

Sample

import KakaoSDKCommon
import KakaoSDKAuth
import KakaoSDKUser

import KakaoSDKCommon
import RxKakaoSDKCommon
import KakaoSDKAuth
import RxKakaoSDKAuth
import KakaoSDKUser
import RxKakaoSDKUser

Configuration for Login with Kakao Talk*

*This configuration is required for Login with Kakao Talk.

The Login with Kakao Talk allows users to move to Kakao Talk from a service app and go back to the app when the user selects [Accept and Continue] or [Cancel] on Kakao Talk. To implement this process, you must configure these things:

1. Register Allowlist to allow Kakao Talk to run from your service app by referring to Register Allowlist.
2. Set a Custom URL Scheme used to open Kakao Talk.
3. Add the handleOpenUrl() method that asks to open the URL in the AppDelegate.swift file to complete the login process after coming back to the service app.

Sample

import KakaoSDKAuth
...

class AppDelegate: UIResponder, UIApplicationDelegate {
    ...
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        if (AuthApi.isKakaoTalkLoginUrl(url)) {
            return AuthController.handleOpenUrl(url: url)
        }

        return false
    }
    ...
}

import RxKakaoSDKAuth
import KakaoSDKAuth
...

class AppDelegate: UIResponder, UIApplicationDelegate {
    ...
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        if (AuthApi.isKakaoTalkLoginUrl(url)) {
            return AuthController.rx.handleOpenUrl(url: url)
        }

        return false
    }
    ...
}

If you make a project for an app in iOS 13 or higher, UIApplicationSceneManifest is added in the Info.plist file and UISceneDelegate.swift is set to use as a default. If you use UISceneDelegate.swift, add the handleOpenUrl() method in the SceneDelegate.swift file, instead of the AppDelegate.swift file.

If you use the SwiftUI App Life Cycle, add handleOpenUrl() inside the ${PROJECT_NAME}App class using onOpenURL() in the same way with initializing SDK.

Sample

import KakaoSDKAuth
...

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    ...
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let url = URLContexts.first?.url {
            if (AuthApi.isKakaoTalkLoginUrl(url)) {
                _ = AuthController.handleOpenUrl(url: url)
            }
        }
    }
    ...
}

import RxKakaoSDKAuth
import KakaoSDKAuth
...

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    ...
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let url = URLContexts.first?.url {
            if (AuthApi.isKakaoTalkLoginUrl(url)) {
                _ = AuthController.rx.handleOpenUrl(url: url)
            }
        }
    }
    ...
}

import SwiftUI
import KakaoSDKCommon
import KakaoSDKAuth
...

@main
struct SwiftUI_testApp: App {

    ...
    init() {
        // Initialize Kakao SDK.
        KakaoSDK.initSDK(appKey: "NATIVE_APP_KEY")
    }

    var body: some Scene {
        WindowGroup {
            // Handle Custom URL Scheme using onOpenURL().
            ContentView().onOpenURL(perform: { url in
                if (AuthApi.isKakaoTalkLoginUrl(url)) {
                    AuthController.handleOpenUrl(url: url)
                }
            })
        }
    }
    ...

}

Login

The Login API enables users to log in through Kakao Talk or their Kakao Account information.

Login with Kakao Talk

For Login with Kakao Talk, you must configure some settings in advance.

After configuration, call the isKakaoTalkLoginAvailable() method that invokes the loginWithKakaoTalk() method to check if Kakao Talk has been installed on a user's device. loginWithKakaoTalk() runs Kakao Talk and prompts the Consent screen that asks consent.

To handle exceptions, refer to the AuthFailureReason section in API Reference.

Parameter

Sample

// Check if Kakao Talk has been installed.
if (UserApi.isKakaoTalkLoginAvailable()) {
    UserApi.shared.loginWithKakaoTalk {(oauthToken, error) in
        if let error = error {
            print(error)
        }
        else {
            print("loginWithKakaoTalk() success.")

            // Do something
            _ = oauthToken            
        }
    }    
}

// Class member property
let disposeBag = DisposeBag()

// Check if Kakao Talk has been installed.
if (UserApi.isKakaoTalkLoginAvailable()) {   
    UserApi.shared.rx.loginWithKakaoTalk()
        .subscribe(onNext:{ (oauthToken) in
            print("loginWithKakaoTalk() success.")
        
            // Do something
             _ = oauthToken
        }, onError: {error in
            print(error)
        })
    .disposed(by: disposeBag)
}

When a user consents, Kakao identifies the user with the user's Kakao Account information linked to Kakao Talk, and then issues tokens. The iOS SDK provides the issued tokens through the OAuthToken object.

OAuthToken

The issued tokens are stored through the TokenManagerProvider class. The stored tokens are automatically added to the authorization header when calling the token-based APIs.

Login with Kakao Account

For Login with Kakao Account, call the loginWithKakaoAccount() method that runs a web browser and prompts the Consent screen that asks consent.

Parameter

Sample

UserApi.shared.loginWithKakaoAccount {(oauthToken, error) in
        if let error = error {
            print(error)
        }
        else {
            print("loginWithKakaoAccount() success.")            

            // Do something
             _ = oauthToken            
        }
    }

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.loginWithKakaoAccount()
    .subscribe(onNext:{ (oauthToken) in
        print("loginWithKakaoAccount() success.")

        // Do something
        _ = oauthToken        
    }, onError: {error in
        print(error)
    })
    .disposed(by: disposeBag)

When a user consents, Kakao identifies the user through the user's Kakao Account cookie stored on the default web browser and then issues tokens through the OAuthToken class.

Advanced: Request reauthentication

You can request reauthentication regardless of a user's login status to enhance security. Set prompts to .LOGIN, and pass it when calling loginWithKakaoAccount(). Then, the login screen is prompted even though a user has already been logged in on the same web browser on the device.

Sample

UserApi.shared.loginWithKakaoAccount(prompts:[.Login]) {(oauthToken, error) in
    if let error = error {
        print(error)
    }
    else {
        print("loginWithKakaoAccount() success.")           
        
        // Do something
        _ = oauthToken
            
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.loginWithKakaoAccount(prompts: [.Login])
    .subscribe(onNext:{ (oauthToken) in
        print("loginWithKakaoAccount() success.")

        // Do something
        _ = oauthToken        
    }, onError: {error in
        print(error)
    })
    .disposed(by: disposeBag)

Check token presence

To check if a user has obtained an access token through Kakao Login, call the hasToken() method in AuthApi. This API returns the presence of an access token or refresh token as a boolean type. However, note that the return value true does not guarantee that the user is in a logged-in state.

Sample

if (AuthApi.hasToken()) {
    UserApi.shared.accessTokenInfo { (_, error) in
        if let error = error {
            if let sdkError = error as? SdkError, sdkError.isInvalidTokenError() == true  {
                //Login is required.
            }
            else {
                //Handle other errors.
            }
        }
        else {
            //Succeeded in validating token (Token is refreshed if needed).
        }
    }
}
else {
    //Login is required.
}

// Class member property
let disposeBag = DisposeBag()
                    
if (AuthApi.hasToken()) {
    UserApi.shared.rx.accessTokenInfo()
        .subscribe(onSuccess:{ (_) in
            //Succeeded in validating token (Token is refreshed if needed).
        }, onFailure: {error in
            if let sdkError = error as? SdkError, sdkError.isInvalidTokenError() == true  {
                //Login is required.
            }
            else {
                //Handle other errors.
            }
        })
        .disposed(by: disposeBag)
}
else {
    //Login is required.
}

If the value false is returned, it means that a token does not exist. In this case, implement a process for a user to log in to issue a token. On the other hand, if the return value is true, you can validate the access token that the user has through the accessTokenInfo() method in UserApi, and then proceed as follows depending on the request result:

• If the request is successful, the access token information is returned,
  • Access token is valid, which means the user does not need to log in.
  • You can call the Kakao APIs with the access token.
• If an error occurs,
  • Access and refresh tokens are invalid, which means the user needs to log in.
  • You need to handle errors by referring to API Reference.

Logout

The Logout API deletes the access and refresh token issued through the login process to have a user log out. You need to call the logout() method in UserApi class.

Regardless of the result of the logout request, the iOS SDK deletes the access and refresh tokens and has the login session end.

Sample

UserApi.shared.logout {(error) in
    if let error = error {
        print(error)
    }
    else {
        print("logout() success.")
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.logout()
    .subscribe(onCompleted:{
        print("logout() success.")
    }, onError: {error in
        print(error)
    })
    .disposed(by: disposeBag)

Unlink

The Unlink API unlinks a user's Kakao Account from a service app. Call the unlink() method defined in the UserApi class.

If the request is successful, the iOS SDK deletes the access and refresh tokens. As the issued tokens are deleted, the session between an app and a user is disconnected, and the user is logged out and unlinked from your app.

Sample

UserApi.shared.unlink {(error) in
    if let error = error {
        print(error)
    }
    else {
        print("unlink() success.")
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.unlink()
    .subscribe(onCompleted:{
        print("unlink() success.")
    }, onError: {error in
        print(error)
    })
    .disposed(by: disposeBag)

Retrieve token information

You can simply check the validity of the access token and refresh token, instead of requesting user information. Call the accessTokenInfo() method in the UserApi.

Sample

// Retrieve the expiration time of the access token.
UserApi.shared.accessTokenInfo {(accessTokenInfo, error) in
    if let error = error {
        print(error)
    }
    else {
        print("accessTokenInfo() success.")

        // Do something
        _ = accessTokenInfo        
    }
}

// Class member property
let disposeBag = DisposeBag()

// Retrieve the expiration time of the access token.
UserApi.shared.rx.accessTokenInfo()
    .subscribe(onSuccess:{ (accessTokenInfo) in        
        print("accessTokenInfo() success.")

        // Do something
        _ = accessTokenInfo 
        
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

AccessTokenInfo

Retrieve user information

To retrieve the information of the user who is currently logged in, call me() method defined in the UserApi class through the shared object.

Sample

UserApi.shared.me() {(user, error) in
    if let error = error {
        print(error)
    }
    else {
        print("me() success.")
        
        // Do something
        _ = user
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.me()
    .subscribe (onSuccess:{ user in
        print("me() success.")
        
        // Do something
        _ = user        
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

The user information in response to this request is passed to the User class defined in KakaoSDKUser. For example, you can access user.id to retrieve Service user ID, user.kakaoAccount.profile for Kakao Account's profile information, user.kakaoAccount.email for email.

User

Ensure that you need to handle exceptions for the following cases in which you cannot get the user information:

• If you do not enable the consent item for some user information.
• If a user has not agreed to provide the user information to the third-party service.
• If a user has not provided the user information to Kakao.

Store user information

You can store or update additional user information into the user property keys that you designated in [My Application] > [User Properties].

Call the updateProfile() method defined in the UserApi class through the shared object.

Parameter

Sample

Here is an example of updating age_range.

UserApi.shared.updateProfile(properties: ["age_range":"20~30"]) {(error) in
    if let error = error {
        print(error)
    }
    else {
        print("updateProfile() success.")
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.updateProfile(properties:["age_range":"20~30"])
    .subscribe(onCompleted:{
        print("updateProfile() success.")  
    }, onError: {error in
        print(error)
    })
    .disposed(by: disposeBag)

Request additional consent

This API prompts the Consent screen to request additional permission or specific personal information for the service if the user has not agreed once logging in with Kakao. Before using this API, read Understand concepts > Request additional consent thoroughly for a better understanding.

Before requesting additional consent, you can check if a user has consented to the scope with the {FIELD_NAME}_needs_agreement key.

Call the loginWithKakaoAccount() method defined in the UserApi class. Pass the scopes of user information you want to request additional consent through scopes as an array of strings.

loginWithKakaoAccount() presents the Consent screen asking consent to the requested scope. When a user chooses to provide the scope and selects [Accept and Continue] on the Consent screen, new tokens are issued, and the scope information is updated in the OAuthToken class.

Parameter

Sample

Here is an example of checking which scopes are required to get consent with the me() method and requesting additional consent by passing scopes when calling loginWithKakaoAccount().

UserApi.shared.me() { (user, error) in
    if let error = error {
        print(error)
    }
    else {
        
        if let user = user {            
            
            //Add the desired scope among the list of all scopes.
            var scopes = [String]()
            if (user.kakaoAccount?.profileNeedsAgreement == true) { scopes.append("profile") }
            if (user.kakaoAccount?.emailNeedsAgreement == true) { scopes.append("account_email") }
            if (user.kakaoAccount?.birthdayNeedsAgreement == true) { scopes.append("birthday") }
            if (user.kakaoAccount?.birthyearNeedsAgreement == true) { scopes.append("birthyear") }
            if (user.kakaoAccount?.genderNeedsAgreement == true) { scopes.append("gender") }
            if (user.kakaoAccount?.phoneNumberNeedsAgreement == true) { scopes.append("phone_number") }
            if (user.kakaoAccount?.ageRangeNeedsAgreement == true) { scopes.append("age_range") }
            if (user.kakaoAccount?.ciNeedsAgreement == true) { scopes.append("account_ci") }
            
            if scopes.count > 0 {
                // If OpenID Connect (OIDC) is enabled,
                // - When "openid" is added to `scopes`, OIDC is applied.
                // - When "openid" is not added to `scopes`, OAuth 2.0 is applied. 
                                                    
                // To use OIDC, add "openid" to `scopes`.
                // scopes.append("openid")
                
                // The tokens are refreshed for the designated scopes.
                UserApi.shared.loginWithKakaoAccount(scopes: scopes) { (_, error) in
                    if let error = error {
                        print(error)
                    }
                    else {
                        UserApi.shared.me() { (user, error) in
                            if let error = error {
                                print(error)
                            }
                            else {
                                print("me() success.")
                                
                                // Do something
                                _ = user
                            }
                        }
                    }
                }
            }
            else {
                print("Not need to get additional consent.")
            }
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.me()
    .map({ (user) -> User in

        //Add the desired scope among the list of all scopes.
        var scopes = [String]()
        
        if (user.kakaoAccount?.profileNeedsAgreement == true) { scopes.append("profile") }
        if (user.kakaoAccount?.emailNeedsAgreement == true) { scopes.append("account_email") }
        if (user.kakaoAccount?.birthdayNeedsAgreement == true) { scopes.append("birthday") }
        if (user.kakaoAccount?.birthyearNeedsAgreement == true) { scopes.append("birthyear") }
        if (user.kakaoAccount?.genderNeedsAgreement == true) { scopes.append("gender") }
        if (user.kakaoAccount?.phoneNumberNeedsAgreement == true) { scopes.append("phone_number") }
        if (user.kakaoAccount?.ageRangeNeedsAgreement == true) { scopes.append("age_range") }
        if (user.kakaoAccount?.ciNeedsAgreement == true) { scopes.append("account_ci") }
        
        if (scopes.count > 0) {

            // If OpenID Connect (OIDC) is enabled,
            // - When "openid" is added to `scopes`, OIDC is applied.
            // - When "openid" is not added to `scopes`, OAuth 2.0 is applied. 
                                                
            // To use OIDC, add "openid" to `scopes`.
            // scopes.append("openid")

            throw SdkError(scopes:scopes)
        }
        else {
            return user
        }
    })
    .retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
    .subscribe(onSuccess:{ ( user ) in
        print("me() success.")

        // Do something
        _ = user
        
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

Retrieve consent details

This API enables you to retrieve the detailed information of the scopes (consent items) that a user has agreed to. You can check all scopes set in [My Application] > [Kakao Login] > [Consent Items] and the details of the scopes. If a user has consent to the scope before, the scope is included in the response even though your app is currently not using the scope.

Call the scopes() method in the UserApi class.

Parameter

Sample

UserApi.shared.scopes() { (scopeInfo, error) in
    if let error = error {
        self?.errorHandler(error: error)
    }
    else {
        self?.success(scopeInfo)
        
        // Do something
        _ = scopeInfo
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.scopes()
    .subscribe(onSuccess:{ (scopeInfo) in
        self.success(scopeInfo)
        
        // Do something
        _ = scopeInfo
                                    
    }, onFailure: {error in
        self.errorHandler(error: error)
    })
    .disposed(by: self.disposeBag)

You can also retrieve the information of specific scopes by passing scope IDs. In this case, the response includes only the detailed information of the specified scopes if the request is successful.

UserApi.shared.scopes(scopes: ["account_email","gender"]) { (scopeInfo, error) in
    if let error = error {
        self?.errorHandler(error: error)
    }
    else {
        self?.success(scopeInfo)
        
        // Do something
        _ = scopeInfo
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.scopes(scopes: ["account_email","gender"])
    .subscribe(onSuccess:{ (scopeInfo) in
        self.success(scopeInfo)
        
        // Do something
        _ = scopeInfo
                                    
    }, onFailure: {error in
        self.errorHandler(error: error)
    })
    .disposed(by: self.disposeBag)

Return data

ScopeInfo

scope

Revoke consent

This API revokes the scope that a user has agreed to. Call the revokeScopes() method in the UserApi class.

Parameter

Sample

UserApi.shared.revokeScopes(scopes: ["account_email","gender"]) { (scopeInfo, error) in
    if let error = error {
        self?.errorHandler(error: error)
    }
    else {
        self?.success(scopeInfo)
        
        // Do something
        _ = scopeInfo
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.revokeScopes(scopes: ["account_email","gender"])
    .subscribe(onSuccess:{ (scopeInfo) in
        self.success(scopeInfo)
        
        // Do something
        _ = scopeInfo
                                    
    }, onFailure: {error in
        self.errorHandler(error: error)
    })
    .disposed(by: self.disposeBag)

Advanced: Manual signup

The Manual signup API manually links a user with your app to complete signup when the Auto-link is disabled.

To figure out if the currently logged-in user needs to be linked with your app, check the value of hasSignedUp in the response of the Retrieving user information API and handle each case:

• true: The user is already linked with your app. You do not need to call the Manual signup API.
• false: The user is not linked with your app. You must call signup() to link the user with your app manually.
• nil: Your app is using the Auto-link feature. You do not need to call the Manual signup API.

If the return value of hasSignedUp is false and the user is ready to sign up, call the signup() method to complete the signup.

Parameter

Sample

UserApi.shared.signup { (userId, error) in
    if let error = error {
        print(error)
    }
    else {
        print("signup() success.")
    }
}

// Class member property
let disposeBag = DisposeBag()

UserApi.shared.rx.signup()
    .subscribe (onSuccess:{ (userId) in
        print("signup() success.")        
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

If the request is successful, the user's service ID is returned.

To check the request result, request the Retrieving user information API again and check the value of hasSignedUp since the user's linked status is not provided even when the request is successful.

Legacy

To see how to integrate Kakao Login using the Legacy Kakao SDK for iOS, click this button. It is highly recommended to migrate to the new version of iOS SDK as soon as possible because the Legacy version may not be supported anymore.

Kakao Login Guide for Legacy iOS SDKUser Guide for Legacy iOS SDK

See more

Download iOS SDKAPI Reference for ReactiveX iOSoutlinkAPI Reference for iOS SDKoutlink