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.

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.

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
enum CBPeripheralManagerAuthorizationStatus

Values representing the current authorization state of the peripheral manager.

Deprecated

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.

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 Authorization Level for Location Services

Choose the appropriate level of access to location data for your app.

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.