Article

Accessing Protected Resources

Request user permission to access restricted resources by providing a purpose string that explains why you need the access.

Overview

Modern devices collect and store a wealth of sensitive information about their users. Many apps rely on this kind of data and the device hardware that generates it to do useful work. For example, a navigation app needs the user’s current GPS coordinates to locate the user on a map. But not all apps need access to all data. The same navigation app doesn’t need the user’s health history, camera interface, or Bluetooth peripherals.

Your app should access only what it needs to do its job. To support this principle, Apple’s operating systems restrict access to protected data and resources by default. Apps can request access on a case-by-case basis, providing an explanation for why they need access. The user decides whether to grant or deny the request.

Provide a Purpose String

The first time your app attempts to access a protected resource, the system prompts the user for permission. In the following example, an iOS app called MyRoute that provides directions generates a prompt requesting access to the user’s location:

Screenshot of a system-generated iOS alert view asking if the app "MyRoute" should be allowed to access location data, including a usage description message from the app’s developer.

If the user grants permission, the system remembers the user’s choice and doesn’t prompt again. If the user denies permission, the access attempt that initiated the prompt and any further attempts fail in a resource-specific way. And for the particular case of access to location data, the user can choose to allow access for only one session by tapping Allow Once.

The system automatically generates the prompt’s title, which includes the name of your app. You supply a message called a purpose string or a usage description—in this case, “Your location is used to provide turn-by-turn directions to your destination”to indicate the reason that your app needs the access. Accurately and concisely explaining to the user why your app needs access to sensitive data, typically in one complete sentence, lets the user make an informed decision and improves the chances that they’ll grant access.

You provide a usage description by setting a string value for a resource-specific key that you add to your app’s Information Property List file. The message shown above, for example, is a string associated with the NSLocationWhenInUseUsageDescription key. Modify your Info.plist file using the property list editor built into Xcode:

Screenshot of an app’s information property list highlighting the added NSLocationWhenInUseUsageDescription key and associated string value that matches the message seen in the previous figure.

App Review checks for the use of protected resources, and rejects apps that contain code accessing those resources without a purpose string. For example, an app accessing contacts might receive the following information from App Review about the requirement that an NSContactsUsageDescription key be present:

ITMS-90683: Missing Purpose String in Info.plist - Your app’s code references
one or more APIs that access sensitive user data. The app’s Info.plist file
should contain a NSContactsUsageDescription key with a user-facing purpose
string explaining clearly and completely why your app needs the data.

To resolve this issue, provide a purpose string that explains why the app needs access to this sensitive information, or remove the code that’s accessing the resource.

Check for Authorization

Many system frameworks that provide access to protected resources have dedicated APIs for checking and requesting authorization to use those resources. This allows you to adjust your app’s behavior depending on the current access it has. For example, if the user denies your app permission to do something, you can remove related elements from your user interface.

Because a user can change authorization at any time using Settings, always check the authorization status of a feature before accessing it. In cases without a dedicated API, like HomeKit, be prepared to gracefully handle access failures.

Reset Authorization Access

When your app attempts to access a protected resource after its first attempt, the system remembers the user’s permission choice and doesn’t prompt again. To prompt the user again, you must reset access to these resources on your device or system.

To reset permission acess to a protected resource in iOS apps, tap Settings > General > Reset > Reset Location & Privacy on your device.

To reset permissions for a particular service in macOS apps, run the tccutil reset <service name> command in Terminal. For example, to reset all permissions for AppleEvents, type:

$ tccutil reset AppleEvents

This command resets authorization access for all apps using the protected resource. You can similarly specify AddressBook, Calendar, Reminders, or other services to reset them individually.

Topics

Apple Events

property list key NSAppleEventsUsageDescription

A message that tells the user why the app is requesting the ability to send Apple events.

Name: Privacy - AppleEvents Sending Usage Description

Bluetooth

property list key NSBluetoothPeripheralUsageDescription

A message that tells the user why the app is requesting the ability to connect to Bluetooth peripherals.

Name: Privacy - Bluetooth Peripheral Usage Description
Deprecated
property list key NSBluetoothAlwaysUsageDescription

A message that tells the user why the app needs access to Bluetooth.

Name: Privacy - Bluetooth Always Usage Description
Beta

Calendar and Reminders

property list key NSCalendarsUsageDescription

A message that tells the user why the app is requesting access to the user’s calendar data.

Name: Privacy - Calendars Usage Description
property list key NSRemindersUsageDescription

A message that tells the user why the app is requesting access to the user’s reminders.

Name: Privacy - Reminders Usage Description
Accessing the Event Store

Request access to a user's calendar data through the event store.

Camera and Microphone

property list key NSCameraUsageDescription

A message that tells the user why the app is requesting access to the device’s camera.

Name: Privacy - Camera Usage Description
property list key NSMicrophoneUsageDescription

A message that tells the user why the app is requesting access to the device’s microphone.

Name: Privacy - Microphone Usage Description
Requesting Authorization for Media Capture on iOS

Respect user privacy by seeking permission to capture and store photos, audio, and video.

Requesting Authorization for Media Capture on macOS

Prompt the user to authorize access to the camera and microphone.

Contacts

property list key NSContactsUsageDescription

A message that tells the user why the app is requesting access to the user’s contacts.

Name: Privacy - Contacts Usage Description

Face ID

property list key NSFaceIDUsageDescription

A message that tells the user why the app is requesting the ability to authenticate with Face ID.

Name: Privacy - Face ID Usage Description
Logging a User into Your App with Face ID or Touch ID

Supplement your own authentication scheme with biometric authentication, making it easy for users to access sensitive parts of your app.

Folders and Files

property list key NSDesktopFolderUsageDescription

A message that tells the user why the app needs access to the user’s Desktop folder.

Name: Privacy - Desktop Folder Usage Description
Beta
property list key NSDocumentsFolderUsageDescription

A message that tells the user why the app needs access to the user’s Documents folder.

Name: Privacy - Documents Folder Usage Description
Beta
property list key NSDownloadsFolderUsageDescription

A message that tells the user why the app needs access to the user’s Downloads folder.

Name: Privacy - Downloads Folder Usage Description
Beta
property list key NSRemovableVolumesUsageDescription

A message that tells the user why the app needs access to files on a removable volume.

Name: Privacy - Removable Volumes Usage Description
Beta
property list key NSNetworkVolumesUsageDescription

A message that tells the user why the app needs access to files on a network volume.

Name: Privacy - Network Volumes Usage Description
Beta
property list key NSFileProviderDomainUsageDescription

A message that tells the user why the app needs access to files managed by a file provider.

Name: Privacy - Access to a File Provider Domain Usage Description
Beta
property list key NSFileProviderPresenceUsageDescription

A message that tells the user why the app needs to be informed when other apps access files that it manages.

Name: Privacy - File Provider Presence Usage Description
Beta

Health

property list key NSHealthShareUsageDescription

A message to the user that explains why the app requested permission to read samples from the HealthKit store.

Name: Privacy - Health Share Usage Description
property list key NSHealthUpdateUsageDescription

A message to the user that explains why the app requested permission to save samples to the HealthKit store.

Name: Privacy - Health Update Usage Description
property list key NSHealthClinicalHealthRecordsShareUsageDescription

A message to the user that explains why the app requested permission to read clinical records.

Name: Privacy - Health Records Usage Description
Setting Up HealthKit

Set up and configure your HealthKit store.

Protecting User Privacy

Respect and safeguard your user’s privacy.

Home

property list key NSHomeKitUsageDescription

A message that tells the user why the app is requesting access to the user’s HomeKit configuration data.

Name: Privacy - HomeKit Usage Description
Enabling HomeKit in Your App

Declare your app’s intention to use HomeKit, and get permission from the user to access home automation accessories.

Location

property list key NSLocationUsageDescription

A message that tells the user why the app is requesting access to the user’s location information.

Name: Privacy - Location Usage Description
property list key NSLocationWhenInUseUsageDescription

A message that tells the user why the app is requesting access to the user’s location information while the app is running in the foreground.

Name: Privacy - Location When In Use Usage Description
property list key NSLocationAlwaysAndWhenInUseUsageDescription

A message that tells the user why the app is requesting access to the user’s location information at all times.

Name: Privacy - Location Always and When In Use Usage Description
Choosing the Location Services Authorization to Request

Determine the authorization your app needs to access location data.

Motion

property list key NSMotionUsageDescription

A message that tells the user why the app is requesting access to the device’s accelerometer.

Name: Privacy - Motion Usage Description
class func authorizationStatus() -> CMAuthorizationStatus

Returns a value indicating whether the app is authorized to retrieve stored motion data.

Music and Media

property list key NSAppleMusicUsageDescription

A message that tells the user why the app is requesting access to the user’s media library.

Name: Privacy - Media Library Usage Description
class func requestAuthorization((MPMediaLibraryAuthorizationStatus) -> Void)

Displays a user interface so that the user can authorize whether your app may view the media library's contents.

NFC

property list key NFCReaderUsageDescription

A message that tells the user why the app is requesting access to the device’s NFC hardware.

Name: Privacy - NFC Scan Usage Description

Photos

property list key NSPhotoLibraryUsageDescription

A message that tells the user why the app is requesting access to the user’s photo library.

Name: Privacy - Photo Library Usage Description
property list key NSPhotoLibraryAddUsageDescription

A message that tells the user why the app is requesting write-only access to the user’s photo library.

Name: Privacy - Photo Library Additions Usage Description
Requesting Authorization to Access Photos

Prepare your app to ask for permission when accessing the user's photo library.

Siri

property list key NSSiriUsageDescription

A message that tells the user why the app is requesting to send user data to Siri.

Name: Privacy - Siri Usage Description
Requesting Authorization to Use SiriKit

Request permission from the user so that Siri and Maps can communicate with your Intents app extension.

Speech Recognition

property list key NSSpeechRecognitionUsageDescription

A message that tells the user why the app is requesting to send user data to Apple’s speech recognition servers.

Name: Privacy - Speech Recognition Usage Description
Asking Permission to Use Speech Recognition

Ask the user’s permission to perform speech recognition using Apple’s servers.

System Administration

property list key NSSystemAdministrationUsageDescription

A message in macOS that tells the user why the app is requesting to manipulate the system configuration.

Name: Privacy - System Administration Usage Description

TV Provider

property list key NSVideoSubscriberAccountUsageDescription

A message that tells the user why the app is requesting access to the user’s TV provider account.

Name: Privacy - Video Subscriber Account Usage Description

See Also

Supporting Privacy

Encrypting Your App’s Files

Protect the user’s data in iOS by encrypting it on disk.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software