App

This document provides information about an Kakao Developers app.

An app is a Kakao Developers project where service information is registered. By configuring a service with the app, you can use various features provided by Kakao Developers and call Kakao APIs with the app key.

General

App basic information

On the app management page, you can check and modify the basic information of the service that will use the Kakao API registered when creating Kakao Developers app in [App] > [General] > [App basic information].

🅐 App icon: Service logo or app icon. File size must be under 250 KB; a size of 128×128 or less is recommended. 🅑 App name (required): Service name. 🅒 Company name (required): Business, corporation, or organization name operating your service. 🅓 Category (required): The category that best fits your service.

Use of basic information

The basic information registered in the app is exposed to users, so it must be entered exactly as in the actual service. As shown in the image below, it is displayed on the Kakao Login consent screen, Manage Connected Services, and the source section at the bottom of Kakao Talk Messages.

App type

Kakao Developers apps can have types as below depending on the permissions they have. An app can hold multiple permissions at the same time. For how to obtain each permission, see the details in each item.

• Basic app: An app with no permissions granted.
• Biz app
• Test app

App management

Each service should have exactly one app. If you are already using Kakao Login or Kakao Talk Share, and thus have an existing app registered, continue using that existing app. Do not register a new one. If you lose access to the administrator account and cannot use the existing app, request an app owner change on DevTalk.

App ID

A unique ID that identifies the app is assigned when an app is created. The app ID can be found on the app management page or in the app information section at the top of the tools page. When you make inquiries on DevTalk, share your app ID. Then, you can receive faster responses.

Business information

On the app management page, you can register the service's business information in [App] > [General] > [Business information] to switch to Biz app.

Biz app additional features

A Biz app is an app with registered business information, providing the following additional features.

• Available to connect to a business channel of the same business registration number in [App] > [Request additional features] on the app management page
• Available to set the consent item [Email] as a required consent
• Available to set subdomains
• Available to use Kakao Sync
• Available to use Retrieve a list of Kakao Talk friends API
• Available to use Kakao Talk Message APIs
• Available to Request for app permissions

Switch to a Biz app

In [App] > [General] > [Business Information], select [Register business information] and enter the Business registration number. Only the app Owner can switch to a Biz app. Individual developers without a business registration number should refer to Switch to a Biz app for an individual.

Switch to a Biz app for an individual

The Biz app is also available for individuals, celebrities, or governmental entities without a business registration number. If the app meets the guidelines below, it can be switched to a Biz app in [App] > [General] > [Business information] on the app management page.

• The app's OWNER must complete the user identification process on [Account settings] at the top right side of Kakao Developers
• Consent to Terms and Conditions of Use for Kakao Business.

A Biz app for individual developers cannot be connected to a Business Channel because it lacks business information. If you need to adopt Kakao Sync, you can still register business information in [App] > [Business Information] even after converting to a Biz app for individual developers.

Switch to Biz app for overseas businesses

You can only switch to a Biz app if you register a business registration number or complete phone number verification.

If you do not have a Korean business registration number or cannot verify your phone number overseas, send the following information to the administrator via a DevTalk message. After reviewing the information, the administrator switches your app to a Biz app.

• License that can verify your overseas business
• Applicant's Kakao Account
• App ID
• App name
• Kakao API or Kakao Developers feature you want to use

App keys

An app key is a unique identification key issued for each platform to use the Kakao API. On the app management page, you can check it in [App] > [General] > [App key].

The app keys are issued by the platform. If an app key is used on the wrong platform, an error response is returned.

• Native app key: Used to initialize the Kakao SDK for Android or initialize the Kakao SDK for iOS.
• REST API key: Used to call APIs using a REST API.
  Pass this key in the HTTP request header when you send a request in a server environment.
• JavaScript key: Used to initialize the Kakao SDK for JavaScript SDK.
• Admin key: Used to call the APIs intended for administrators using a REST API. Be sure that your app’s Admin key does not get exposed because this key has all permissions.

Reissue

If one of the app keys is revealed, the app Owner can reissue the app keys. Make sure that the reissue is irreversible. After the reissue, the app keys in the service app or website must be changed to the reissued value.

Note: Admin key

The Admin Key is a fixed key used to authorize API access and is critical information that must never be exposed. For information security, use the Admin Key only for server-side calls and ensure it is not included in source code.

Platform

Kakao APIs are only allowed to the services that registered platform information. To register platform information, go to [App] > [General] > [Platform].

Note: Error due to incorrect platform information

If the registered platform information is different from the actual service, invalid android_key_hash or ios_bundle_id or web_site_url error occurs. In this case, check the list below.

• Android: Check if the registered [Package name] is the same as the value of the package attribute in AndroidManifest.xml and if a Key hash is registered.
• iOS: Check if the registered [Bundle ID] is the same as the value of the [Project] > [TARGETS] > [General] > [Identity] > [Bundle Identifier].
• Web: Check if the site domain used to call the Kakao API is registered.

Note: Market URL

A market URL is an open market URL registered in [Platform]. Messages sent by Kakao Talk Share or Kakao Talk Message APIs provide a link to launch the service app. If the service app is not installed on the user's device when launching the service app, the market URL will be opened.

Android

🅐 Package Name

• Unique identifier of the Android app
• Enter the value of the package attribute in AndroidManifest.xml

🅑 Market URL

• If [Google Play] is selected, market URL is automatically entered with [Package Name]
• If [Enter directly] is selected, enter the full market URL, such as One store

🅒 Key hash

• Key hashes to authenticate for Kakao API requests
• Refer to Key hashes and register key hashes by the development environment

iOS

🅐 Bundle ID

• Unique identifier of the iOS app
• Enter the value of [Bundle Identifier] in the Xcode project information

🅑 Appstore ID and Market URL

• Enter the App ID in the Appstore
• Market URL is automatically entered with [App ID]

Web

🅐 Site domain

• Required to use Kakao SDK for JavaScript, Kakao Talk Share, Kakao Talk Message API
• Enter the site domain in http, https, file format
• If the service website is served with both http and https, enter either one of them
• Up to 10 site domains are allowed by default
  • To register more than 10 site domains, set wildcard subdomains or request permission (Note: Restrictions on the number of site domain and how to add additional site domains)

🅑 Default domain

• If more than one site domain is registered, the site domain registered on the top line is set to the default domain
• Default domain is used as the default value for the link in the message that sent by Kakao Talk Share or Kakao Talk Message APIs

Note: Wildcard subdomains

Biz app is allowed to set wildcard subdomains Kakao Login Redirect URIs. When using subdomains containing wildcard characters, refer to the rules below.

• Domains with wildcard characters cannot be the default domain
• If only domains with wildcard characters are registered, some functions may not work properly
• Each subdomain must include a unique domain name or hostname
  • https://*.sample.com (O)
  • https://*.com (X)
• Subdomains cannot include wildcard characters in the middle of the domain
  • https://*.sample.com (O)
  • https://sub.*.sample.com (X)
• Subdomains cannot include more than two wildcard characters
  • https://*.sample.com (O)
  • https://*.*.sample.com (X)

Test app

The test app is provided for updating or adding a new feature to the service. The test app has built-in permissions to preview features before requesting a review. Belows are the main features that the test app provides

• Additional features for test apps to preview features before submitting a review of the original app
• Available to use independent test app settings that differ from the original app settings
• Permissions are automatically applied to the test app when permissions are added or deleted to the original app (Ex: Kakao Business privacy review or separate permissions for APIs, such as Kakao Social, Messages, and Talk Calendar)

Limitations

Consider the limitations below when using test apps.

• Creation and deletion
  • Only the Biz app can create the test app.
  • Up to 5 apps can be created per original app.
  • Deletion of an original app is not possible if it has test apps.
• Team management
  • At the time of initial creation, the OWNER and team members of the test app are the same as those of the original app.
    • When the OWNER of the original app is changed, the test app OWNER is also changed, and the test app OWNER cannot be changed separately.
    • Team members of the test app, excluding the OWNER, can be added or removed independently of the original app.
  • A separate maximum team member limit is applied.
• Feature usage
  • Only team members of the test app can use the test app.
  • For the below products, APIs that require permissions can only be called by the team members of the test app, even if the original app has acquired the permissions. The response range is also limited to those team members.
    • Kakao Talk Message, Kakao Talk Social, Talk Calendar.
  • A separate quota limit is applied.

Additional features for test apps

Below is the complete list of permissions provided for the default test app. To use additional permissions in the original app, you need to obtain the permissions separately by reviewing.

• Basic features and permissions of the app
• Additional features and permissions for the Biz app
• Available consent type in the Personal information (provide additional required or optional consent permissions)
  • Email (account_email): Required
  • Name (name): Optional, Required
  • Gender (gender): Required
  • Age range (age_range): Required
  • Birthday (birthday): Required
  • Birthyear (birthyear): Optional, Required
  • Phone number (phone_number): Optional, Required
  • Shipping information (recipient name, shipping address, phone number) (shipping_address): Optional, Required
• Kakao Login: Set Simple Signup
• Kakao Login: Retrieve shipping address

How to create

To create a test app, go to [App] > [General] > [Test App], and select 🅐 [Create a test app].

The test app provides a separate app key, independent settings, and permissions that differ from the original app.

Even if you are not the owner of the original app, the account that created the test app becomes the owner of the test app. The owner of the test app can select the 🅑 name of the test app created in the [Test App] section to navigate to the test app settings screen.

App deletion

If the app is no longer needed or if you have been guided to delete your Kakao Developers app on another platform, you can delete it as follows.

1. Select the app you want to delete from [App].
2. Go to [App] > [General] > [App deletion], and click [Delete app permanently].
3. Enter the App name of the app to delete, then click [Delete].

Note: Conditions that prevent app deletion

An app cannot be deleted under the following conditions. Q. Why can't I delete the app? can also be referenced.

• You are not the app Owner (OWNER).
• The app is connected to a Kakao Talk Channel.
• A test app is in use.
• A Biz Wallet is connected.
• The app is being used with Kakao Sync integration on an e-commerce platform.

Kakao Talk Channel

You can use Kakao Talk Channel connected to your Kakao Developers app for marketing purposes. For the method to connect the app and Kakao Talk Channel, see Connect Kakao Talk Channel to app.

🅐 Connected Kakao Talk Channel 🅑 Primary channel 🅒 Customer management API policy agreement

Connected Kakao Talk Channel

You can check and manage the list of Kakao Talk Channels connected to the app.

Click [Manage Kakao Talk Channel] to navigate to the Request additional features page. To connect the app and Kakao Talk Channel, click [Request] in the [Connect Kakao Talk Channel] column to request a connection. To disconnect, select [Disconnect] in the [Connection Management] section.

You can check the list of Kakao Talk Channels connected to the app and select [Disconnect] if needed to disconnect them. Disconnected Kakao Talk Channels can be reconnected by selecting [Request] for [Connect Kakao Talk Channel] in [App] > [Request additional features] on the app management page.

Primary channel

A primary channel is the Kakao Talk Channel that represents your service. When a primary channel is set, the consent item for adding the channel is displayed on the Kakao Login consent screen. To see how to set, see Primary channel.

Customer management API policy agreement

You can agree to the required policies to use the Kakao Talk Channel customer management API. See the step-by-step guide below.

1. Connect Kakao Talk Channel to the app.
2. In the app management page, select [App] > [Kakao Talk Channel] > [Customer management API policy agreement], then select [Agree] to open the guide window. Only the app Owner account can agree to the policy.
3. After reviewing the information notice about user personal information protection and management responsibility in the guide window, select [Save] if you agree with the content.
4. Refer to the Developer documentation and call the API. For details about the Kakao Talk Channel customer management API, see Kakao Talk Channel customer management.

Request additional features

Request a review to use additional features of the app. The list of additional features that can be applied for can be found in Request permission.

Request a review on the app management page at [App] > [Request additional features]. Before applying for additional features, complete Check eligibility. Refer to the instructions for each item below.

For information on checking the Kakao Talk Channel list and disconnecting, see Connected Kakao Talk Channel.

🅐 Check eligibility 🅑 Business information 🅒 Additional features

Check eligibility

Checks the app and account's qualifications to request for app permissions.

1. If you do not meet the Conditions for checking eligibility, guidance related to 🅐 Check eligibility will be displayed. Follow the instructions to configure your app or account.
2. If you meet the Conditions for checking eligibility, a [Confirm Qualifications] button will appear under 🅐 Check eligibility. Click this button to open a window for checking eligibility.
3. After reviewing and agreeing to the details, the check eligibility will be completed.

Conditions for checking eligibility

• Owner or Editor role: The access account requires app OWNER or EDITOR role.
• Identity verification: If the identity verification is not incompleted, follow the instructions to verify your identity.
• Biz app: If the app is not a Biz app, swiching to a Biz app is required. (See Biz-app)

Available features to request

Business information

Requests for business information verification for the app.

1. Business verification is available after Check eligibility. Until then, the [Request] is disabled.
2. When selecting [Request] for 🅑 Business information, the [Business information] input window opens.
3. Fill in the inputs by referring to the instructions and cautions for each item, and request.

List of additional features

Requests a review for your app to use additional features. You can find the features you can request in the Request additional features list.

1. Additional feature review can be requested only after Check eligibility is completed. Before that, [Request] in the 🅒 Additional features list is deactivated.
2. When you select [Request] in the 🅒 Additional features, the review request window opens. If you attempt to request a feature that requires Business information review before it is completed, the business information review window opens first. After submitting the business information review, you can proceed to request the additional feature review.
3. Fill in and submit the input fields with reference to the guidance and cautions for each item. You can check the review status in the [Review status] column, and the approval or rejection of the requested review will also be sent to the email registered with the account.

Review status

Displays the status of the permission review as below.

• In progress: The review has been requested and is currently being reviewed by a staff member.
• Approved: The request has been approved and the app has been granted permission.
• Partially approved: The request has been partially approved and the app has been granted part of the permission.
• Rejected: The request was not approved and the app was not granted permission, need to resubmit with deficiencies.
• Already approved: Permission to use the corresponding additional feature is already granted.

Contact

If you have any questions regarding the request for additional features, contact us through the [추가 기능 신청] (meaning 'Additional feature request') board or by message on DevTalk. For swift response, include your App ID when making an inquiry.

Webhook

Register settings related to webhooks to receive notifications about user activities or account status changes that occur outside the service. For the details, see Webhook.

If webhook testing is required, select [Webhook test] for simple testing. For the details, see Webhook test.

Account status change webhook

On the app management page, go to [App] > [Webhook] > [Account status change webhook], then select [Register webhook] to configure the Account status change webhook. Enter the detailed information with reference to the descriptions below.

🅐 Activation status: Select [Enabled] to enable Account status change webhook. 🅑 Webhook URL: Set a webhook URL of your service that receives Account status change event information. The domain for the webhook supports HTTPS only. 🅒 Change Event: Select Change event types of each category. ⓐ Categories: Select a desired category. Provided only to the app with permission. ⓑ Types: Select desired change event types.

After entering the detailed information, select [Save] to display the registered webhook details. Select [Edit] to modify the registered information, or select [Delete] to remove it.

These settings alone do not activate the webhook feature. You must also implement a server that can process webhook requests. For more details, see Implementation steps.

Unlink webhook

On the app management page, select [App] > [Webhook] > [Unlink webhook], then select [Register webhook] to configure the Unlink webhook. Enter the detailed information with reference to the descriptions below.

Enter the site domain address, method, and request path (Path) for processing webhooks in the [Webhook URL] field. Only HTTPS is supported for webhook URLs to protect user information, and only port 443 can be registered.

After entering the detailed information, select [Save] to display the registered webhook details. Select [Edit] to modify the registered information, or select [Delete] to remove it.

The webhook will not operate with only these settings. A receiving server capable of processing webhook requests must also be implemented. For the details, see Implementation steps.

Kakao Talk Share webhook

On the app management page, select [App] > [Webhook] > [Kakao Talk Share webhook], then select [Register webhook] to configure the Kakao Talk Share webhook. Enter the detailed information with reference to the description below.

Enter the site domain address, method, and request path for processing webhooks in the [Method] and [Webhook URL] fields. Only HTTPS is supported for webhook URLs to protect user information, and only port 443 can be registered.

After entering the detailed information, select [Save] to display the registered webhook details. Select [Edit] to modify the registered information, or select [Delete] to remove it.

The webhook feature will not operate with only these settings. A receiving server capable of processing webhook requests must also be implemented. For the details, see Implementation procedure. In addition, the Kakao Talk Share webhook can only be received after Custom parameter configuration are completed.

Kakao Talk Channel webhook

On the app management page, select [App] > [Webhook] > [Kakao Talk Channel webhook], then select [Register webhook] to configure the Kakao Talk Channel webhook. The Kakao Talk Channel webhook can be configured after connecting Kakao Talk Channel to the app.

Registering a [webhook URL] alone does not activate the webhook feature. A receiving server capable of processing webhook requests must also be implemented. For details, see Implementation procedure.

When a webhook is implemented, the webhook is sent to all business Kakao Talk Channels connected to the app. You can check the target Kakao Talk Channels in [App] > [Kakao Talk Channel] > [Connected Kakao Talk Channel] on the app management page.

Member

A member is a person who manages the app. You can manage members in the [App] > [Member] section of the app management page. Only developer accounts registered as members can view or modify app information, and for a test app, only members can call Kakao APIs.

Member role

• Owner
  • App owner
  • Has all permissions for the app, such as view and edit app information, reissue app keys, delete the app, and request additional features.
• Editor
  • Can view and edit app information, and request additional features.
  • Cannot delete the app, invite team members, or reissue app keys.
• Message Editor
  • Can view app information, and register or edit message templates.
• Viewer
  • Can only view app information.

How to manage

🅐 Add member

• [Kakao Account (email)]: Enter the email address of the developer account to invite and select the permission to grant.
  • Only email addresses used for Kakao Account login can be invited as members. An email is sent to the address upon invitation.
  • Kakao Account can be registered on the Kakao Account page.
• [Role]: Select the member role to grant to the invited developer account.

🅑 Member information and management

• Kakao Account: Kakao Account email of the member.
• Role: Role granted to the member.
• State: Member state.
  • Active: User who has completed Kakao Developers registration and member registration.
  • Invitation email sent: User who has not registered for Kakao Developers yet. Can join as a member after receiving the invitation email and completing registration.
  • Dormant: User whose Kakao Account is dormant. The Kakao Account email of the dormant user is not exposed to any member, including the owner. Dormant members cannot be edited and can only be removed.
• Management
  • Provides the ability to modify or remove member permissions.
  • The owner can select [Edit] to change the role for each member (including transferring owner permission to another member) or select [Delete] to remove a member.
  • A member can select [Leave] to remove themselves from the member list.

How to change Owner

1. Log in with the developer account that owns the app.
2. On the account management page, go to [App] > [Member] > [Add member], and add the developer account to become the new app owner as a member.
   • To use a new Kakao Account, register a new Kakao Account, log in to Kakao Developers, and complete developer registration.
3. In the member list, select [Edit] and change the permission to Owner.

If the app Owner is unknown or missing, refer to FAQ.

Advanced

Allowed IP address

This feature allows the Kakao API server to accept requests only from registered IP addresses to prevent security incidents such as app key leakage. In the app management page, go to [App] > [Advanced] > [Allowed IP addresses], then select [Register IP address] to register the service server's IP address. It is recommended to configure with CIDR (IP/CIDR) or Subnet Mask (IP/Mask) information, but individual IP addresses (IPv4, IPv6) can also be registered. Multiple IP addresses can be added by line breaks.

Allowed IP address setting is applied to all Kakao API calls with the REST API key or the Admin key. After any IP address is registered, only REST API calls from the registered IP address will be allowed. If a request has been sent from an unregistered IP address, the following error is returned. To solve this issue, register the IP address of the server to send a request from, or disable this feature.

"msg": "ip mismatched! callerIp=XXX.XXX.XXX.XXX. check out registered ips.",
"code": -401

To disable this feature, delete all registered IP addresses by clicking [Delete].