Request user permission to access restricted resources by providing a purpose string that explains why you need the access.
Framework
- UIKit
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:

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 Info
file. The message shown above, for example, is a string associated with the NSLocationWhenInUseUsageDescription key. Modify your Info
file using the property list editor built into Xcode:

For more information about an app’s information property list, see About Information Property List Files.
Important
If you link on or after iOS 10, or on or after macOS 10.14, your app crashes if you try to access certain protected resources without providing a corresponding purpose string. Even if it’s not required, it’s always best to provide a usage string if your app uses a protected resource.
The following table lists the purpose string keys for different resources, and the platforms on which they are required to gain access to the given resource.
Resource | Purpose string key in | Required in |
---|---|---|
Apple Events | NSAppleEventsUsageDescription | macOS |
Bluetooth | iOS | |
Calendar | iOS, macOS | |
Camera | iOS, macOS | |
Contacts | iOS, macOS | |
Face ID | iOS | |
Health | NSHealthShareUsageDescription, | iOS |
HomeKit | iOS | |
Location | NSLocationWhenInUseUsageDescription, NSLocationAlwaysUsageDescription, NSLocationAlwaysAndWhenInUsageDescription | iOS |
Location | macOS | |
Microphone | iOS, macOS | |
Motion | iOS | |
Music and media | iOS | |
NFC | iOS | |
Photos | NSPhotoLibraryUsageDescription, NSPhotoLibraryAddUsageDescription | iOS, macOS |
Reminders | iOS, macOS | |
Siri | iOS | |
Speech recognition | iOS |
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.
The following table provides links to information about how to gain or check access to various resources from within your app.
Resource | Checking or getting access |
---|---|
Apple Events | When your app first attempts to control another app using Apple Events, the system presents an authorization request to the user. There’s no explicit API for requesting or testing availabilty. Be prepared to handle any access failures gracefully. |
Bluetooth | Use the |
Calendar and Reminders | See Accessing the Event Store in the EventKit framework. |
Camera and Microphone | See Requesting Authorization for Media Capture on iOS in the AVFoundation framework. |
Contacts | See the methods in Privacy Access in the |
Face ID | See Logging a User into Your App with Face ID or Touch ID in the LocalAuthentication framework. |
HealthKit | See Setting Up HealthKit and Protecting User Privacy in the HealthKit framework. |
HomeKit | When your app first attempts to access a property of the |
Location | See Choosing the Authorization Level for Location Services and Determining the Availability of Location Services. |
Motion | See the methods in Determining Activity Availability in the |
Music and media | See the methods in Getting the Default Media Library in the |
Photos | |
Siri | |
Speech recognition | See the methods in Requesting Authorization from the User in the |