Developer Documentation｜Application Permissions

For more information, please visit open platform

I. Intro

Lark uses permissions to control app feature and determine if an app can call a particular API and get or update certain fields. A permission has three properties: field, API and event.

•Field: The field an app has permission to access. If the "Obtain user email address" permission is enabled, the app can access the email address field.

•API: Permission must be enabled to invoke certain APIs. To invoke the "Send message" API, the "Send messages as an app" permission must be enabled.

•Event: Permission is also required to subscribe to certain events and obtain the corresponding field. For example, if you want to "Obtain private messages sent from a user to a bot", you will have to subscribe to the "Receive messages" event.

Different permissions are available for different types of apps. Some permissions apply to both custom apps and public apps, while others only apply to custom apps.

II. Steps

Enabling permissions

Administrators can apply for app permissions in Lark Developer. On the app details page, click Permissions in the menu on the left and then enable the permissions needed for the app. The permissions will only go into effect after the next version of the app has been submitted and approved.

Basic permissions

Basic permissions are lower risk and can be enabled by developers as needed. The following basic permissions are provided:

Permission Name	Fields	API	Event	Available for	Notes
Obtain basic user information	name, avatar, description	Batch obtain user information	-	Custom apps Public apps	User name, profile picture, and description
Obtain department information	id, name, chat_id, status	Obtain department details, Batch obtain department details	-	Custom apps Public apps
Send messages as an app	-	Send Message Card	-	Custom apps Public apps	Can only be enabled if bot feature is enabled
Obtain private messages sent from a user to a bot	-	-	Events - Recieve messages	Custom apps Public apps	Can only be enabled if bot feature is enabled
Obtain user messages @ a bot in a group chat	-	-	Events - Recieve messages	Custom apps Public apps	Can only be enabled if bot feature is enabled
Verify if a user is an app administrator	-	Verify application administrator	-	Custom apps Public apps	Finds out if a user has permission to manage an app

Advanced permissions

•Advanced permissions requested by custom apps are reviewed by organization administrators after the app has been submitted for review.

•The advanced permissions requested by public apps are highlighted on the app page in the Lark App Directory. Organization administrators will consider the permissions required when assessing whether to use the app.

Only request permissions that your app needs to function properly. Otherwise, the organization administrator (for custom apps)/the platform operator (for public apps) may reject your app or decide not to use it.

User

Permission Name	Fields	API	Available for	Notes
Obtain user’s email	email	Batch obtain user information	Custom apps Public apps
Obtain user’s mobile number	mobile	Batch obtain user information	Custom apps
Obtain user’s user ID	user_id or employee_id	Batch obtain user information	Custom apps
Obtain user’s ID using an email address or mobile number	open_id, user_id	Get user IDs using email addresses or mobile numbers	Custom apps Public apps
Operate a cloud doc as a user	-	Integration Overview	Custom apps Public apps
Obtain user’s unified ID	union_id		Custom apps Public apps

Messages

Permission Name	Fields	API	Available for	Notes
Send messages to multiple users	-	Send Message Card	Custom apps Public apps
Send messages to users in one or multiple departments	-	Send Message Card	Custom apps Public apps

Group chat

Permission Name	Fields	API	Available for	Notes
Obtain group information	id, chatType, userType, avatarUrls, name, i18nNames	chooseChat, getChatInfo	Custom apps Public apps

Contacts

Permission Name	Fields	API	Event	Available for	Notes
Obtain user’s employment information	employee_no, employee_type, status, is_tenant_manager, join_time, update_timecountry, city, work_station, custom_attrs	Batch obtain user information	-	Custom apps Public apps	Obtains a user’s work information
Obtain user’s gender	gender	Batch obtain user information	-	Custom apps Public apps
Obtain user’s management information	departments, leader_open_id	Batch obtain user information	-	Custom apps Public apps	Obtains the user’s department and supervisor
Obtain role	role_list, id(role), name(role)	Obtain a department user list	-	Custom apps Public apps
Obtain department management information	parent_id, leader_open_id, sub-department information, department user information, and custom user properties	Obtain a sub-department list, Obtain a department user list, Obtain department user details, Obtain custom user properties	-	Custom apps Public apps	Gets department management information, including sub-departments, the department manager, department members, and custom properties. Permission to access user information is required to get department user details
Update contacts	-	Update a user’s information, Update department information	-	Custom apps
Access Contacts as an app	-	Obtain the Contacts permission scope	Events - Contacts updates	Custom apps Public apps	The app must have permission to access Contacts
Search users	-	Search Users	-	Custom apps Public apps

Manage apps

Permission Name	Fields	API	Available for	Notes
Manage app visibility	-	Update the availability of an app	Custom apps
Obtain app information	-	Obtain the availability of an app in an organization, Obtain the apps installed by an organization	Custom apps	Obtains a department/user list by app visibility, and a list of apps installed by an organization
Obtain the apps visible to a user	app_list, app_id, primary_language, app_name, description, avatar_url, app_scene_type, status	Obtain the apps available to a user	Custom apps

Lark Suite

Permission Name	Fields	API	Event	Available for	Notes
Access the calendar	-	Calendar APIs	-	Custom apps Public apps
Access the Approvals app	-	Approvals APIs	Approvals Event Guide	Custom apps Public apps
Obtain a meeting room	room_id, building_id, building_name, capacity, description, display_id, floor_name, is_disabled, name	Query meeting room details	-	Custom apps Public apps

Related Articles